diff --git a/locales/en/LC_MESSAGES/messages.po b/locales/en/LC_MESSAGES/messages.po new file mode 100644 index 00000000..5e49a179 --- /dev/null +++ b/locales/en/LC_MESSAGES/messages.po @@ -0,0 +1,3972 @@ +msgid "" +msgstr "" +"Project-Id-Version: pyos-python-package-guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-04-30 18:44-0600\n" +"PO-Revision-Date: 2025-05-01 18:41\n" +"Last-Translator: \n" +"Language-Team: English\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=2; plural=(n != 1);\n" +"X-Crowdin-Project: pyos-python-package-guide\n" +"X-Crowdin-Project-ID: 785976\n" +"X-Crowdin-Language: en\n" +"X-Crowdin-File: /translation2/locales/templates/LC_MESSAGES/tutorials.pot\n" +"X-Crowdin-File-ID: 50\n" +"Language: en_US\n" + +#: ../../tutorials/add-license-coc.md:1 +msgid "Add a `LICENSE` & `CODE_OF_CONDUCT` to your Python package" +msgstr "" + +#: ../../tutorials/add-license-coc.md:3 +msgid "In the [previous lesson](add-readme) you:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:5 +msgid " Created a basic `README.md` file for your scientific Python package" +msgstr "" + +#: ../../tutorials/add-license-coc.md:7 +msgid " Learned about the core components that are useful to have in a `README` file." +msgstr "" + +#: ../../tutorials/add-license-coc.md:9 +#: ../../tutorials/add-readme.md:10 +msgid "Learning objectives" +msgstr "" + +#: ../../tutorials/add-license-coc.md:12 +#: ../../tutorials/add-readme.md:12 +#: ../../tutorials/installable-code.md:41 +#: ../../tutorials/pyproject-toml.md:22 +#: ../../tutorials/setup-py-to-pyproject-toml.md:15 +msgid "In this lesson you will learn:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:14 +msgid "How to select a license and add a `LICENSE` file to your package repository, with a focus on the GitHub interface." +msgstr "" + +#: ../../tutorials/add-license-coc.md:15 +msgid "How to add a `CODE_OF_CONDUCT` file to your package repository." +msgstr "" + +#: ../../tutorials/add-license-coc.md:16 +msgid "How you can use the Contributors Covenant website to add generic language as a starting place for your `CODE_OF_CONDUCT`." +msgstr "" + +#: ../../tutorials/add-license-coc.md:19 +msgid "What is a license?" +msgstr "" + +#: ../../tutorials/add-license-coc.md:21 +msgid "A license contains legal language about how users can use and reuse your software. To set the `LICENSE` for your project, you:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:23 +msgid "Create a `LICENSE` file in your project directory that specifies the license that you choose for your package." +msgstr "" + +#: ../../tutorials/add-license-coc.md:24 +msgid "Reference that file in your `pyproject.toml` data where metadata are set." +msgstr "" + +#: ../../tutorials/add-license-coc.md:26 +msgid "By adding the `LICENSE` file to your `pyproject.toml` file, the `LICENSE` will be included in your package's metadata which is used to populate your package's PyPI landing page. The `LICENSE` is also used in your GitHub repository's landing page interface." +msgstr "" + +#: ../../tutorials/add-license-coc.md:28 +msgid "What license should you use?" +msgstr "" + +#: ../../tutorials/add-license-coc.md:30 +msgid "We suggest that you use a permissive license that accommodates the other most commonly used licenses in the scientific Python ecosystem (MIT[^mit] and BSD-3[^bsd3]). If you are unsure, use MIT given it's the generally recommended license on [choosealicense.com](https://choosealicense.com/)." +msgstr "" + +#: ../../tutorials/add-license-coc.md:33 +msgid "Licenses for the scientific Python ecosystem" +msgstr "" + +#: ../../tutorials/add-license-coc.md:34 +msgid "[We discuss licenses for the scientific Python ecosystem in more detail here in our guidebook.](../documentation/repository-files/license-files)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:37 +msgid "Where should the `LICENSE` file live" +msgstr "" + +#: ../../tutorials/add-license-coc.md:39 +msgid "Your `LICENSE` file should be placed at the root of your package's repository. When you add the `LICENSE` at the root, GitHub will automagically discover it and provide users with a direct link to your `LICENSE` file within your GitHub repository." +msgstr "" + +#: ../../tutorials/add-license-coc.md:45 +msgid "Image showing the GitHub repository for SunPy an accepted pyOpenSci package." +msgstr "" + +#: ../../tutorials/add-license-coc.md:47 +msgid "Notice at the top of the README portion of the GitHub landing page, there are three tabs directly linking to the `README` file which is visible, the `CODE_OF_CONDUCT` file and one that specifies the license that SunPy uses. These files are discovered by GitHub because they are placed in the root of the project directory using standard naming conventions." +msgstr "" + +#: ../../tutorials/add-license-coc.md:54 +msgid "How to add a `LICENSE` file to your package directory" +msgstr "" + +#: ../../tutorials/add-license-coc.md:56 +msgid "There are several ways to add a `LICENSE` file:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:58 +msgid "When you create a new repository on GitHub, it will ask you if you wish to add a `LICENSE` file at that time. If you select yes, it will create the file for you." +msgstr "" + +#: ../../tutorials/add-license-coc.md:59 +msgid "You can add a `LICENSE` through the GitHub gui following the [ instructions here](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository)." +msgstr "" + +#: ../../tutorials/add-license-coc.md:60 +msgid "You can add the file manually as we are doing in this lesson." +msgstr "" + +#: ../../tutorials/add-license-coc.md:63 +msgid "If you completed the past lessons including" +msgstr "" + +#: ../../tutorials/add-license-coc.md:65 +msgid "[Making your code installable](installable-code.md) and" +msgstr "" + +#: ../../tutorials/add-license-coc.md:66 +msgid "[publishing your package to PyPI](publish-pypi.md)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:68 +msgid "then you already have a `LICENSE` file containing text for the MIT license in your Python package. Thus you can skip to the next section of this tutorial which walks you through adding a `CODE_OF_CONDUCT`." +msgstr "" + +#: ../../tutorials/add-license-coc.md:70 +msgid "If you don't yet have a `LICENSE` file in your directory, then continue reading." +msgstr "" + +#: ../../tutorials/add-license-coc.md:73 +msgid "How to add a `LICENSE` to your package - the manual way" +msgstr "" + +#: ../../tutorials/add-license-coc.md:75 +msgid "If you don't already have a `LICENSE` file, and you are not yet using a platform such as GitHub or GitLab, then you can create a `LICENSE` file by" +msgstr "" + +#: ../../tutorials/add-license-coc.md:77 +msgid "Create a new file called `LICENSE`. If you are using shell you can type:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:84 +msgid "Go to [choosealicense.com](https://choosealicense.com/)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:85 +msgid "Select permissive license" +msgstr "" + +#: ../../tutorials/add-license-coc.md:86 +msgid "It will suggest that you use the [MIT license](https://choosealicense.com/licenses/mit/)." +msgstr "" + +#: ../../tutorials/add-license-coc.md:87 +msgid "Copy the license text that it provides into your `LICENSE` file that you created above." +msgstr "" + +#: ../../tutorials/add-license-coc.md:88 +msgid "Save your file. You're all done!" +msgstr "" + +#: ../../tutorials/add-license-coc.md:90 +msgid "An overview of licenses in the scientific Python ecosystem" +msgstr "" + +#: ../../tutorials/add-license-coc.md:93 +msgid "In the pyOpenSci [packaging guidebook](../documentation/repository-files/license-files), we provide an overview of licenses in the scientific Python ecosystem. We review why license files are important, which ones are most commonly used for scientific software and how to select the correct license." +msgstr "" + +#: ../../tutorials/add-license-coc.md:95 +msgid "If you want a broad overview of why licenses are important for protecting open source software, [check out this blog post that overviews the legal side of things.](https://opensource.guide/legal/#just-give-me-the-tldr-on-what-i-need-to-protect-my-project)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:0 +msgid "Instructions for adding a `LICENSE` file within the GitHub interface" +msgstr "" + +#: ../../tutorials/add-license-coc.md:0 +msgid "Add license: new GitHub repository" +msgstr "" + +#: ../../tutorials/add-license-coc.md:106 +msgid "When you create a new GitHub repository you can add a `LICENSE` file through the GitHub interface." +msgstr "" + +#: ../../tutorials/add-license-coc.md:111 +msgid "Screenshot of the create new repository interface that GitHub provides. The elements of this are the owner and repository name for the new repo. Below that you can add a description of the repository. Below that you can set it to be public or private. At the bottom of the interface there is an Add a README checkbox where it will add a blank readme file for you. At the very bottom there is a line to add a .gitignore file and another to choose a license." +msgstr "" + +#: ../../tutorials/add-license-coc.md:113 +msgid "Image showing the GitHub interface that allows you to add a `LICENSE` and `README` file when you create a new repository." +msgstr "" + +#: ../../tutorials/add-license-coc.md:0 +msgid "Add `LICENSE`: Existing GitHub repository" +msgstr "" + +#: ../../tutorials/add-license-coc.md:119 +msgid "If you already have a GitHub repository for your package, then you can add a `LICENSE` using the GitHub interface by adding a new file to the repository." +msgstr "" + +#: ../../tutorials/add-license-coc.md:121 +msgid "Follow the instructions to select and add a license to your repository on the [GitHub LICENSE page](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository) ." +msgstr "" + +#: ../../tutorials/add-license-coc.md:122 +msgid "Once you have added your `LICENSE` file, be sure to sync your git local repository with the repository on GitHub.com. This means running `git pull` to update your local branch." +msgstr "" + +#: ../../tutorials/add-license-coc.md:125 +msgid "Image showing what the LICENSE file looks like in the GItHub interface. At the top you can see the actual license which in this image is BSD 3-clause New or revised license. Then there is some text describing both what the license is and the associated permissions for that specific license. At the bottom of the image, the actual text for the license is shown in the LICENSE file." +msgstr "" + +#: ../../tutorials/add-license-coc.md:127 +msgid "You can view a summary of the `LICENSE` chosen on your project's GitHub landing page." +msgstr "" + +#: ../../tutorials/add-license-coc.md:134 +msgid "Now you know how to add a `LICENSE` to your project. Next, you'll learn about the `CODE_OF_CONDUCT.md` file and how to add it to your package directory." +msgstr "" + +#: ../../tutorials/add-license-coc.md:139 +msgid "What is a code of conduct file?" +msgstr "" + +#: ../../tutorials/add-license-coc.md:141 +msgid "A `CODE_OF_CONDUCT` file is used to establish guidelines for how people in your community interact." +msgstr "" + +#: ../../tutorials/add-license-coc.md:143 +msgid "This file is critical to supporting your community as it grows. The `CODE_OF_CONDUCT`:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:146 +msgid "Establishes guidelines for how users and contributors interact with each other and you in your software repository." +msgstr "" + +#: ../../tutorials/add-license-coc.md:147 +msgid "Identifies negative behaviors that you don't want in your interactions." +msgstr "" + +#: ../../tutorials/add-license-coc.md:149 +msgid "You can use your code of conduct as a tool that can be referenced when moderating challenging conversations." +msgstr "" + +#: ../../tutorials/add-license-coc.md:151 +msgid "What to put in your `CODE_OF_CONDUCT` file" +msgstr "" + +#: ../../tutorials/add-license-coc.md:153 +msgid "If you are unsure of what language to add to your `CODE_OF_CONDUCT` file, we suggest that you adopt the [contributor covenant language](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) as a starting place." +msgstr "" + +#: ../../tutorials/add-license-coc.md:156 +msgid "![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:156 +msgid "Contributor Covenant" +msgstr "" + +#: ../../tutorials/add-license-coc.md:158 +msgid "The `CODE_OF_CONDUCT.md` should be placed at the root of your project directory, similar to the `LICENSE` file." +msgstr "" + +#: ../../tutorials/add-license-coc.md:160 +msgid "How to add a `CODE_OF_CONDUCT` file to your package directory" +msgstr "" + +#: ../../tutorials/add-license-coc.md:162 +msgid "Add a `CODE_OF_CONDUCT.md` file to the root of your repository if it doesn't already exist." +msgstr "" + +#: ../../tutorials/add-license-coc.md:168 +msgid "Visit the [contributor covenant website](https://www.contributor-covenant.org/) and add [the markdown version of their code of conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/code_of_conduct.md) to your `CODE_OF_CONDUCT.md` file. Be sure to fill in any placeholder information. Read the text closely to ensure you both understand it and also agree with its contents!" +msgstr "" + +#: ../../tutorials/add-license-coc.md:170 +msgid "That's it - you've now added a code of conduct to your package directory." +msgstr "" + +#: ../../tutorials/add-license-coc.md:172 +msgid "Additional Code of Conduct resources" +msgstr "" + +#: ../../tutorials/add-license-coc.md:175 +msgid "[ Guide: `CODE_OF_CONDUCT.md` files](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:176 +msgid "[pyOpenSci package guide `CODE_OF_CONDUCT.md` overview](https://www.pyopensci.org/python-package-guide/documentation/repository-files/code-of-conduct-file.html)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:179 +#: ../../tutorials/add-readme.md:233 +#: ../../tutorials/publish-conda-forge.md:463 +#: ../../tutorials/pyproject-toml.md:673 +msgid " Wrap up" +msgstr "" + +#: ../../tutorials/add-license-coc.md:181 +msgid "In this lesson and the [last lesson](add-readme), you have added a:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:183 +msgid "`README` file;" +msgstr "" + +#: ../../tutorials/add-license-coc.md:184 +msgid "`LICENSE` file and a" +msgstr "" + +#: ../../tutorials/add-license-coc.md:185 +msgid "`CODE_OF_CONDUCT` file." +msgstr "" + +#: ../../tutorials/add-license-coc.md:187 +msgid "These are fundamental files needed for every scientific Python package repository. These files help users understand how to use your package and interact with package maintainers." +msgstr "" + +#: ../../tutorials/add-license-coc.md:191 +msgid "In the upcoming lessons, you will:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:193 +msgid "[Add more metadata to your `pyproject.toml` file](pyproject-toml) to support building and publishing your package on PyPI." +msgstr "" + +#: ../../tutorials/add-license-coc.md:194 +msgid "Publish a new version of your Python package to the test PyPI to preview the updated metadata landing page." +msgstr "" + +#: ../../tutorials/add-license-coc.md:199 +#: ../../tutorials/installable-code.md:642 +#: ../../tutorials/publish-conda-forge.md:475 +#: ../../tutorials/publish-pypi.md:394 +msgid "Footnotes" +msgstr "" + +#: ../../tutorials/add-license-coc.md:201 +msgid "https://opensource.org/license/mit/" +msgstr "" + +#: ../../tutorials/add-license-coc.md:202 +msgid "https://opensource.org/license/bsd-3-clause/" +msgstr "" + +#: ../../tutorials/add-readme.md:1 +msgid "Add a README file to your Python package" +msgstr "" + +#: ../../tutorials/add-readme.md:3 +msgid "In the previous lessons you learned:" +msgstr "" + +#: ../../tutorials/add-readme.md:5 +msgid "[What a Python package is](intro.md)" +msgstr "" + +#: ../../tutorials/add-readme.md:6 +msgid "[How to make your code installable](installable-code)" +msgstr "" + +#: ../../tutorials/add-readme.md:7 +msgid "[How to publish your package to (test) PyPI](publish-pypi.md)" +msgstr "" + +#: ../../tutorials/add-readme.md:8 +msgid "[How to publish your package to conda-forge](publish-conda-forge.md)" +msgstr "" + +#: ../../tutorials/add-readme.md:14 +msgid "How to add a **README.md** file to your package." +msgstr "" + +#: ../../tutorials/add-readme.md:15 +msgid "What the core elements of a **README.md** file are." +msgstr "" + +#: ../../tutorials/add-readme.md:18 +msgid "What is a README file?" +msgstr "" + +#: ../../tutorials/add-readme.md:20 +msgid "The `README.md` file is a markdown file located at the root of your project directory that helps a user understand:" +msgstr "" + +#: ../../tutorials/add-readme.md:23 +msgid "You package's name" +msgstr "" + +#: ../../tutorials/add-readme.md:24 +msgid "What the package does. Your README file should clearly state the problem(s) that your software is designed to solve and its target audience." +msgstr "" + +#: ../../tutorials/add-readme.md:25 +msgid "The current development \"state\" of the package (through badges)" +msgstr "" + +#: ../../tutorials/add-readme.md:26 +msgid "How to get started with using your package." +msgstr "" + +#: ../../tutorials/add-readme.md:27 +msgid "How to contribute to your package" +msgstr "" + +#: ../../tutorials/add-readme.md:28 +msgid "How to cite your package" +msgstr "" + +#: ../../tutorials/add-readme.md:30 +msgid "Your **README.md** file is important as it is often the first thing that someone sees before they install your package. The README file is also used to populate your PyPI landing page." +msgstr "" + +#: ../../tutorials/add-readme.md:32 +msgid "Note that there is no specific content structure for README files. However, this tutorial outlines the sections that we suggest that you include in your README file." +msgstr "" + +#: ../../tutorials/add-readme.md:36 +msgid "Create a README.md file for your package" +msgstr "" + +#: ../../tutorials/add-readme.md:38 +msgid "It's time to add a `README.md` file to your project directory." +msgstr "" + +#: ../../tutorials/add-readme.md:40 +msgid "Step 0: Create a README file" +msgstr "" + +#: ../../tutorials/add-readme.md:41 +msgid "To get started, if you don't already have a README.md file in your project directory, create one." +msgstr "" + +#: ../../tutorials/add-readme.md:44 +msgid "If you created your project directory from" +msgstr "" + +#: ../../tutorials/add-readme.md:46 +msgid "a GitHub repository online" +msgstr "" + +#: ../../tutorials/add-readme.md:47 +msgid "using `hatch init`" +msgstr "" + +#: ../../tutorials/add-readme.md:49 +msgid "Then you may already have a README.MD file in your project directory." +msgstr "" + +#: ../../tutorials/add-readme.md:55 +msgid "Step 1: Add the name of your package as the README title" +msgstr "" + +#: ../../tutorials/add-readme.md:57 +msgid "At the top of the `README.md` file, add the name of your package." +msgstr "" + +#: ../../tutorials/add-readme.md:59 +msgid "If you are using markdown it should be a header 1 (H1) tag which is denoted with a single `#` sign." +msgstr "" + +#: ../../tutorials/add-readme.md:61 +msgid "`# Package-title-here`" +msgstr "" + +#: ../../tutorials/add-readme.md:63 +msgid "Step 2: add badges to the top of your README file" +msgstr "" + +#: ../../tutorials/add-readme.md:65 +msgid "It's common for maintainers to add badges to the top of their README files. Badges allow you and your package users to track things like:" +msgstr "" + +#: ../../tutorials/add-readme.md:67 +msgid "Broken documentation and test builds." +msgstr "" + +#: ../../tutorials/add-readme.md:68 +msgid "Versions of your package that are on PyPI and conda." +msgstr "" + +#: ../../tutorials/add-readme.md:69 +msgid "Whether your package has been reviewed and vetted by an organization such as pyOpenSci and/or JOSS." +msgstr "" + +#: ../../tutorials/add-readme.md:71 +msgid "If you have already published your package to pypi.org you can use [shields.io to create a package version badge](https://shields.io/badges/py-pi-version). This badge will dynamically update as you release new versions of your package to PyPI." +msgstr "" + +#: ../../tutorials/add-readme.md:73 +msgid "If not, you can leave the top empty for now and add badges to your README at a later point as they make sense." +msgstr "" + +#: ../../tutorials/add-readme.md:75 +msgid "Step 3: Add a description of what your package does" +msgstr "" + +#: ../../tutorials/add-readme.md:77 +msgid "Below the badges (if you have them), add a section of text that provides an easy-to-understand overview of what your package does." +msgstr "" + +#: ../../tutorials/add-readme.md:81 +msgid "Keep this section short." +msgstr "" + +#: ../../tutorials/add-readme.md:82 +msgid "Try to avoid jargon." +msgstr "" + +#: ../../tutorials/add-readme.md:83 +msgid "Define technical terms that you use to make the description accessible to more people." +msgstr "" + +#: ../../tutorials/add-readme.md:85 +msgid "Remember that the more people understand what your package does, the more people will use it." +msgstr "" + +#: ../../tutorials/add-readme.md:87 +msgid "Step 4: Add package installation instructions" +msgstr "" + +#: ../../tutorials/add-readme.md:89 +msgid "Next, add instructions that tell users how to install your package." +msgstr "" + +#: ../../tutorials/add-readme.md:91 +msgid "For example, can they use pip to install your package? `python -m pip install packagename`" +msgstr "" + +#: ../../tutorials/add-readme.md:94 +msgid "or conda?" +msgstr "" + +#: ../../tutorials/add-readme.md:96 +msgid "`conda install -c conda-forge packagename`." +msgstr "" + +#: ../../tutorials/add-readme.md:98 +msgid "If you haven't yet published your package to pypi.org then you can skip this section and come back and add these instructions later." +msgstr "" + +#: ../../tutorials/add-readme.md:102 +msgid "Step 5: Any additional setup" +msgstr "" + +#: ../../tutorials/add-readme.md:104 +msgid "In some cases, your package users may need to manually install other tools in order to use your package. If that is the case, be sure to add a section on additional setup to your README file." +msgstr "" + +#: ../../tutorials/add-readme.md:109 +msgid "Here, briefly document (or link to documentation for) any additional setup that is required to use your package. This might include:" +msgstr "" + +#: ../../tutorials/add-readme.md:113 +msgid "authentication information, if it is applicable to your package." +msgstr "" + +#: ../../tutorials/add-readme.md:114 +msgid "additional tool installations, such as GDAL." +msgstr "" + +#: ../../tutorials/add-readme.md:117 +msgid "Many packages won't need an additional setup section in their README. In that case you can always skip this section." +msgstr "" + +#: ../../tutorials/add-readme.md:122 +msgid "Step 6: Add a get started section" +msgstr "" + +#: ../../tutorials/add-readme.md:124 +msgid "Next add a get-started section. Within this section, add a small code example that demonstrates importing and using some of the functionality in your package." +msgstr "" + +#: ../../tutorials/add-readme.md:127 +msgid "Provide a fully functional code snippet if possible" +msgstr "" + +#: ../../tutorials/add-readme.md:130 +msgid "It is important to try to make the code examples that you provide your users as useful as possible." +msgstr "" + +#: ../../tutorials/add-readme.md:132 +msgid "Be sure to provide a copy/paste code example that will work as-is when pasted into a Jupyter Notebook or .py file if that is possible." +msgstr "" + +#: ../../tutorials/add-readme.md:134 +msgid "If there are tokens and other steps needed to run your package, be sure to be clear about what those steps are." +msgstr "" + +#: ../../tutorials/add-readme.md:137 +msgid "For the pyosPackage, a short get started demo might look like this:" +msgstr "" + +#: ../../tutorials/add-readme.md:145 +msgid "Or it could simply be a link to a getting started tutorial that you have created. If you don't have this yet, you can leave it empty for the time being." +msgstr "" + +#: ../../tutorials/add-readme.md:148 +msgid "This would also be a great place to add links to tutorials that help users understand how to use your package for common workflows." +msgstr "" + +#: ../../tutorials/add-readme.md:153 +msgid "Step 7: Community section" +msgstr "" + +#: ../../tutorials/add-readme.md:155 +msgid "The community section of your README file is a place to include information for users who may want to engage with your project. This engagement will likely happen on a platform like GitHub or GitLab." +msgstr "" + +#: ../../tutorials/add-readme.md:157 +msgid "In the community section, you will add links to your contributing guide and `CODE_OF_CONDUCT.md`. You will create a [`CODE_OF_CONDUCT.md` file in the next lesson](add-license-coc)." +msgstr "" + +#: ../../tutorials/add-readme.md:160 +msgid "As your package grows you may also have a link to a development guide that contributors and your maintainer team will follow. The development guide outlines how to perform maintenance tasks such as:" +msgstr "" + +#: ../../tutorials/add-readme.md:163 +msgid "running tests" +msgstr "" + +#: ../../tutorials/add-readme.md:164 +msgid "making package releases" +msgstr "" + +#: ../../tutorials/add-readme.md:165 +msgid "building documentation" +msgstr "" + +#: ../../tutorials/add-readme.md:166 +msgid "and more." +msgstr "" + +#: ../../tutorials/add-readme.md:170 +msgid "Step 8: Citation information" +msgstr "" + +#: ../../tutorials/add-readme.md:172 +msgid "Finally it is important to let users know how to cite your package. You can communicate citation information in a few different ways." +msgstr "" + +#: ../../tutorials/add-readme.md:175 +msgid "You can use a tool such as zenodo to create a DOI and associated citation information for your package if it is hosted on a platform such as GitHub. [Check out this short tutorial that covers setting that up.](https://coderefinery.github.io/github-without-command-line/doi/)" +msgstr "" + +#: ../../tutorials/add-readme.md:179 +msgid "Alternatively if you send your package through a peer review process such as the [one lead by pyOpenSci](https://www.pyopensci.org/about-peer-review/index.html). After being accepted by pyOpenSci, if your package is in scope, you can be accepted by the Journal of Open Source Software and get a cross-ref DOI through [our partnership with the Journal of Open Source Software.](https://www.pyopensci.org/about-peer-review/index.html)" +msgstr "" + +#: ../../tutorials/add-readme.md:183 +msgid "The finished README file" +msgstr "" + +#: ../../tutorials/add-readme.md:185 +msgid "Your finished `README.md` file should look something like this:" +msgstr "" + +#: ../../tutorials/add-readme.md:235 +msgid "It's important to consider the information that a new user or contributor might need when creating your `README.md` file. While there is no perfect template, above is a set of recommendations as you are just getting started. You may find the need for other elements to be added to this file as you further develop your package and as a community begins to use your package." +msgstr "" + +#: ../../tutorials/add-readme.md:241 +msgid "In the [next lesson](add-license-coc.md), you will add a LICENSE file to your Python package. A license file is critical as it tells users how they legally can (and can't) use your package. It also:" +msgstr "" + +#: ../../tutorials/add-readme.md:245 +msgid "Builds trust with your users" +msgstr "" + +#: ../../tutorials/add-readme.md:246 +msgid "Discourages misuse of your package and associated code" +msgstr "" + +#: ../../tutorials/command-line-reference.md:1 +#: ../../tutorials/intro.md:54 +msgid "Command Line Reference Guide" +msgstr "" + +#: ../../tutorials/command-line-reference.md:4 +msgid "**What these tables are:** These tables summarize the command line inputs (e.g., `pipx install hatch`, `hatch build`) necessary to complete all steps in the package creation process, from installing Hatch to publishing the package on PyPI and conda-forge." +msgstr "" + +#: ../../tutorials/command-line-reference.md:6 +msgid "**What these tables are not:** These tables do not cover the manual/non-automated steps (e.g., create PyPI account, create PyPI API token) you have to complete throughout the package creation process." +msgstr "" + +#: ../../tutorials/command-line-reference.md:8 +msgid "**Operating system note:** The current iteration of this guide has been tested on the Windows OS only. Many commands are Windows-specific. OS-specific commands are indicated with parentheses after the description of the command, e.g., [COMMAND_DESCRIPTION] (Windows). Corresponding commands for macOS and Linux will be added in the future." +msgstr "" + +#: ../../tutorials/command-line-reference.md:11 +msgid "Environment Setup" +msgstr "" + +#: ../../tutorials/command-line-reference.md:33 +msgid "Package Development" +msgstr "" + +#: ../../tutorials/command-line-reference.md:52 +msgid "Package Publishing" +msgstr "" + +#: ../../tutorials/command-line-reference.md:71 +msgid "Versions and Environments" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:1 +msgid "Get to Know Hatch" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:3 +msgid "Our Python packaging tutorials use the tool [Hatch](https://hatch.pypa.io/latest/). While there are [many great packaging tools](/package-structure-code/python-package-build-tools) out there, we have selected Hatch because:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:8 +msgid "It is an end-to-end tool that supports most of the steps required to create a quality Python package. Beginners will have fewer tools to learn if they use Hatch." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:11 +msgid "It supports different build back-ends if you ever need to compile code in other languages." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:13 +msgid "As a community, pyOpenSci has decided that Hatch is a user-friendly tool that supports many different scientific Python use cases." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:16 +msgid "In this tutorial, you will install and get to know Hatch a bit more before starting to use it." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:19 +msgid "You need two things to successfully complete this tutorial:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:21 +msgid "You need Python installed." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:22 +msgid "You need Hatch installed." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:25 +msgid "If you don't already have Python installed on your computer, Hatch will do it for you when you install Hatch." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:29 +msgid "Install Hatch" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:31 +msgid "To begin, follow the operating-system-specific instructions below to install Hatch." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:0 +msgid "MAC" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:38 +msgid "Follow the instructions [here](https://hatch.pypa.io/latest/install/#installers)." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:40 +msgid "Download the latest GUI installer for MAC [hatch-universal.pkg](https://github.com/pypa/hatch/releases/latest/download/hatch-universal.pkg)." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:41 +msgid "Run the installer and follow the setup instructions." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:42 +msgid "If your terminal is open, then restart it." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:0 +msgid "Windows" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:48 +msgid "In your browser, download the correct `.msi` file for your system: [hatch-x64.msi](https://github.com/pypa/hatch/releases/latest/download/hatch-x64.msi)" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:50 +msgid "Run your downloaded installer file and follow the on-screen instructions." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:0 +msgid "Linux" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:56 +msgid "We suggest that you install Hatch using pipx on Linux. however, if you prefer another method, check out the [Hatch installation documentation](https://hatch.pypa.io/latest/install/) for other methods." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:70 +msgid "Hatch can also be installed directly using [pip](https://hatch.pypa.io/latest/install/#pip) or [conda](https://hatch.pypa.io/latest/install/#conda). We encourage you to follow the instructions above because we have found that the Hatch installers for Windows and Mac are the easiest and most efficient." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:74 +msgid "Our Linux users have found success installing Hatch with pipx if they already use apt install." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:77 +msgid "Both approaches (using a graphical installer on Windows/Mac and pipx) ensure that you have Hatch installed globally. A global install means that Hatch is available across all of your Python environments on your computer." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:82 +msgid "Check that hatch installed correctly" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:84 +msgid "Once you have completed the installation instructions above, you can open your terminal, and make sure that Hatch installed correctly using the command below:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:92 +msgid "*Note the version number output of `hatch --version` will likely be different from the output above in this tutorial.*" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:95 +msgid "Configure Hatch" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:97 +msgid "Once you have installed Hatch, you can customize its configuration. This includes setting the default name and setup for every package you create. While this step is not required, we suggest that you do it." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:101 +msgid "Hatch stores your configuration in a [`config.toml` file](https://hatch.pypa.io/latest/config/project-templates/)." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:103 +msgid "While you can update the `config.toml` file through the command line, it might be easier to look at and update it in a text editor if you are using it for the first time." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:107 +msgid "Step 1: Open and Edit Your `config.toml` File" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:109 +msgid "To open the config file in your file browser, run the following command in your shell:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:112 +msgid "`hatch config explore`" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:114 +msgid "This will open up a directory window that allows you to double-click on the file and open it in your favorite text editor." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:117 +msgid "You can also retrieve the location of the Hatch config file by running the following command in your shell:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:125 +msgid "Step 2 - update your email and name" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:127 +msgid "Once the file is open, update the [template] table of the `config.toml` file with your name and email. This information will be used in any `pyproject.toml` metadata files that you create using Hatch." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:137 +msgid "Step 3" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:139 +msgid "Next, set tests to false in the `[template.plugins.default]` table." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:141 +msgid "While tests are important, setting the tests configuration in Hatch to `true` will create a more complex `pyproject.toml` file. You won't need to use this feature in this beginner friendly tutorial series but we will introduce it in later tutorials." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:146 +msgid "Your `config.toml` file should look something like the one below." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:184 +msgid "Also notice that the default license option is MIT. While we will discuss license in more detail in a later lesson, the MIT license is the recommended permissive license from [choosealicense.com](https://www.choosealicense.com) and as such we will use it for this tutorial series." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:190 +msgid "You are of course welcome to select another license." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:192 +#: ../../tutorials/installable-code.md:22 +#: ../../tutorials/installable-code.md:411 +#: ../../tutorials/installable-code.md:502 +#: ../../tutorials/intro.md:235 +#: ../../tutorials/publish-pypi.md:3 +#: ../../tutorials/publish-pypi.md:178 +#: ../../tutorials/publish-pypi.md:350 +#: ../../tutorials/pyproject-toml.md:718 +msgid "Todo" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:193 +msgid "I think we'd need the SPDX license options here if they want to chose bsd-3 for instance" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:196 +msgid "Step 4: Close the config file and run `hatch config show`" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:198 +msgid "Once you have completed the steps above run the following command in your shell." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:200 +msgid "`hatch config show`" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:202 +msgid "`hatch config show` will print out the contents of your `config.toml` file in your shell. Look at the values and ensure that your name, email is set. Also make sure that `tests=false`." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:206 +msgid "Hatch features" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:208 +msgid "Hatch offers a suite of features that will make creating, publishing and maintaining your Python package easier." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:211 +msgid "Comparison to other tools" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:213 +msgid "[We compared Hatch to several of the other popular packaging tools in the ecosystem including flit, pdm and poetry. Learn more here](package-features)" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:216 +msgid "[More on Hatch here](hatch)" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:218 +msgid "A few features that Hatch offers" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:220 +msgid "It will convert metadata stored in a `setup.py` or `setup.cfg` file to a pyproject.toml file for you (see [Migrating setup.py to pyproject.toml using Hatch](setup-py-to-pyproject-toml.md ))" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:222 +msgid "It will help you by storing configuration information for publishing to PyPI after you've entered it once." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:224 +msgid "Use `hatch -h` to see all of the available commands." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:226 +msgid "What's next" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:228 +msgid "In the next lesson you'll learn how to package and make your code installable using Hatch." +msgstr "" + +#: ../../tutorials/installable-code.md:6 +msgid "Make your Python code installable" +msgstr "" + +#: ../../tutorials/installable-code.md:8 +msgid "What we previously covered" +msgstr "" + +#: ../../tutorials/installable-code.md:9 +msgid "[In the previous lesson](intro), you learned about what a Python package is. You also learned about the [benefits of creating a Python package](package-benefits)." +msgstr "" + +#: ../../tutorials/installable-code.md:13 +msgid "Your next step in our packaging tutorial series is to create a Python package that is installable both locally and remotely from a website such as GitHub (or GitLab). The package that you create in this lesson will have the bare minimum elements needed to be installable into a Python environment." +msgstr "" + +#: ../../tutorials/installable-code.md:18 +msgid "Making your code installable is an important steps towards creating a full Python package that is directly installable from PyPI." +msgstr "" + +#: ../../tutorials/installable-code.md:23 +msgid "Is it clear where to add commands? Bash vs. Python console Bash vs. Zsh is different" +msgstr "" + +#: ../../tutorials/installable-code.md:25 +msgid "Does this lesson run as expected on windows and mac?" +msgstr "" + +#: ../../tutorials/installable-code.md:26 +msgid "ADD: note about what makes something \"package worthy\", with a common misconception being that a package should be production-ready code that's valuable to a broad audience. This may not be a pervasive misconception in Python, but a quick break-out with an explanation of what a package can consist of would be helpful." +msgstr "" + +#: ../../tutorials/installable-code.md:31 +msgid "Diagram showing the basic steps to creating an installable package. There are 4 boxes with arrows pointing towards the right. The boxes read, your code, create package structure, add metadata to pyproject.toml and pip install package." +msgstr "" + +#: ../../tutorials/installable-code.md:33 +msgid "A basic installable package needs a few things: code, a [specific package file structure](https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-structure.html) and a `pyproject.toml` containing your package's name and version. Once you have these items in the correct directory structure, you can pip install your package into any environment on your computer. You will learn how to create a basic installable package in this lesson." +msgstr "" + +#: ../../tutorials/installable-code.md:37 +msgid "About this lesson" +msgstr "" + +#: ../../tutorials/installable-code.md:43 +msgid "How to make your code installable into any Python environment both locally and from GitHub" +msgstr "" + +#: ../../tutorials/installable-code.md:44 +msgid "How to create a basic `pyproject.toml` file that includes package dependencies and metadata. This file is required to make your package installable." +msgstr "" + +#: ../../tutorials/installable-code.md:45 +msgid "How to declare a [build backend](build_backends) which will be used to [build](build-package) and install your package" +msgstr "" + +#: ../../tutorials/installable-code.md:46 +msgid "How to install your package in editable mode for interactive development" +msgstr "" + +#: ../../tutorials/installable-code.md:48 +msgid "**What you need to complete this lesson**" +msgstr "" + +#: ../../tutorials/installable-code.md:50 +msgid "To complete this lesson you will need a local Python environment and shell on your computer. You will also need to have [Hatch installed](get-to-know-hatch)." +msgstr "" + +#: ../../tutorials/installable-code.md:53 +msgid "If you are using Windows or are not familiar with Shell, you may want to check out the Carpentries shell lesson[^shell-lesson]. Windows users will likely need to configure a tool for any Shell and git related steps." +msgstr "" + +#: ../../tutorials/installable-code.md:55 +msgid "**What comes next**" +msgstr "" + +#: ../../tutorials/installable-code.md:57 +msgid "In the upcoming lessons you will learn how to:" +msgstr "" + +#: ../../tutorials/installable-code.md:59 +msgid "[Publish your package to PyPI](publish-pypi)" +msgstr "" + +#: ../../tutorials/installable-code.md:60 +msgid "Add a README file to your package to support community use" +msgstr "" + +#: ../../tutorials/installable-code.md:61 +msgid "Add additional project metadata to your package to support PyPI publication" +msgstr "" + +#: ../../tutorials/installable-code.md:67 +msgid "This diagram has two smaller boxes with arrows pointing to the right to a Python environment. The small boxes read your-package and pip install package. The environment box on the right reads - your Python environment. It them lists your-package along with a few other core packages such as Matplotlib, NumPy, Pandas, Xarray and GeoPandas." +msgstr "" + +#: ../../tutorials/installable-code.md:69 +msgid "Making your code installable is the first step towards creating a publishable Python package. Once your code is installable, it is a Python package and can be added to any Python environment on your computer and imported in the same way that you might import a package such as Pandas or GeoPandas. If your code is on GitHub or GitLab you can also install it directly from there." +msgstr "" + +#: ../../tutorials/installable-code.md:74 +msgid "About the Python package directory structure" +msgstr "" + +#: ../../tutorials/installable-code.md:76 +msgid "To make your Python code installable you need to create a specific directory structure with the following elements:" +msgstr "" + +#: ../../tutorials/installable-code.md:78 +msgid "A `pyproject.toml` file." +msgstr "" + +#: ../../tutorials/installable-code.md:79 +msgid "A specific directory structure." +msgstr "" + +#: ../../tutorials/installable-code.md:80 +msgid "Some code." +msgstr "" + +#: ../../tutorials/installable-code.md:81 +msgid "An `__init__.py` file in your code directory." +msgstr "" + +#: ../../tutorials/installable-code.md:83 +msgid "The directory structure you'll create in this lesson will look like this:" +msgstr "" + +#: ../../tutorials/installable-code.md:95 +msgid "About the basic package directory structure" +msgstr "" + +#: ../../tutorials/installable-code.md:97 +msgid "Notice a few things about the above layout:" +msgstr "" + +#: ../../tutorials/installable-code.md:99 +msgid "Your package code lives within a `src/packagename` directory. We suggest that you use `src` (short for **source code**) directory as it [ensures that you are running tests on the installed version of your code](https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-structure.html#the-src-layout-and-testing)." +msgstr "" + +#: ../../tutorials/installable-code.md:100 +msgid "Within the `src` directory you have a package directory called `pyospackage`. Use the name of your package for that directory name. This will be the name for importing your package in Python code once installed." +msgstr "" + +#: ../../tutorials/installable-code.md:101 +msgid "In your package directory, you have an `__init__.py` file and all of your Python modules. You will learn more about the `__init__.py` file below." +msgstr "" + +#: ../../tutorials/installable-code.md:102 +msgid "The `pyproject.toml` file lives at the root directory of your package." +msgstr "" + +#: ../../tutorials/installable-code.md:103 +msgid "The name of the root directory for the package is **pyospackage** which is the name of the package. This is not a requirement but you will often see that the GitHub / GitLab repository and the root directory name are the same as the package name." +msgstr "" + +#: ../../tutorials/installable-code.md:105 +msgid "What is an `__init__.py` file?" +msgstr "" + +#: ../../tutorials/installable-code.md:107 +msgid "The `__init__.py` file tells Python that a directory should be treated as a Python package. As such, a directory with an `__init__.py` file can be imported directly into Python. The `__init__.py` file does not need to contain any code in order for Python to recognize it; it can be empty." +msgstr "" + +#: ../../tutorials/installable-code.md:111 +msgid "For example, following the file structure example above which has an `__init__.py` file within it, you can run:" +msgstr "" + +#: ../../tutorials/installable-code.md:117 +#: ../../tutorials/pyproject-toml.md:48 +msgid "What is a pyproject.toml file?" +msgstr "" + +#: ../../tutorials/installable-code.md:119 +msgid "The **pyproject.toml** file is:" +msgstr "" + +#: ../../tutorials/installable-code.md:121 +msgid "Where you define your project's metadata (including its name, authors, license, etc)" +msgstr "" + +#: ../../tutorials/installable-code.md:122 +msgid "Where you define dependencies (the packages that it depends on)" +msgstr "" + +#: ../../tutorials/installable-code.md:123 +msgid "Used to specify and configure what build backend you want to use to [build your package](../package-structure-code/python-package-distribution-files-sdist-wheel)." +msgstr "" + +#: ../../tutorials/installable-code.md:125 +msgid "After the `__init__.py` and `pyproject.toml` files have been added, your package can be built and distributed as an installable Python package using tools such as pip. Note that the `pyproject.toml` file needs to have a few basic items defined for the package to be installable including:" +msgstr "" + +#: ../../tutorials/installable-code.md:131 +msgid "The `build-backend` that you want to use," +msgstr "" + +#: ../../tutorials/installable-code.md:132 +msgid "The project `name` and `version`." +msgstr "" + +#: ../../tutorials/installable-code.md:134 +msgid "Why the pyproject.toml file is important" +msgstr "" + +#: ../../tutorials/installable-code.md:138 +msgid "The `pyproject.toml` file replaces some of the functionality of both the `setup.py` file and `setup.cfg` files. If you try to pip install a package with no `pyproject.toml` you will get the following error:" +msgstr "" + +#: ../../tutorials/installable-code.md:150 +msgid "Note about `setup.py`" +msgstr "" + +#: ../../tutorials/installable-code.md:154 +msgid "If your project already defines a `setup.py` file, Hatch can be used to automatically create the `pyproject.toml`." +msgstr "" + +#: ../../tutorials/installable-code.md:155 +msgid "See [Using Hatch to Migrate setup.py to a pyproject.toml ](setup-py-to-pyproject-toml.md)" +msgstr "" + +#: ../../tutorials/installable-code.md:161 +msgid "Time to create your Python package!" +msgstr "" + +#: ../../tutorials/installable-code.md:163 +msgid "Now that you understand the basics of the Python package directory structure, and associated key files (`__init__.py` and `pyproject.toml`), it's time to create your Python package! Below you will create a directory structure similar to the structure described above using Hatch." +msgstr "" + +#: ../../tutorials/installable-code.md:167 +msgid "Step 1: Set Up the Package Directory Structure" +msgstr "" + +#: ../../tutorials/installable-code.md:169 +msgid "Open your shell or preferred terminal." +msgstr "" + +#: ../../tutorials/installable-code.md:170 +msgid "Use the shell `cd` command to navigate in your shell to the location where you'd like your package directory to live. Hatch will create the package directory for you" +msgstr "" + +#: ../../tutorials/installable-code.md:171 +msgid "Choose a name for your package. The name should:" +msgstr "" + +#: ../../tutorials/installable-code.md:172 +msgid "Have no spaces (*Required*)" +msgstr "" + +#: ../../tutorials/installable-code.md:173 +msgid "Use all lowercase characters (*Recommended*). For this tutorial we will use `pyospackage`." +msgstr "" + +#: ../../tutorials/installable-code.md:174 +msgid "Only use letter and the characters _ or - in the name. This means that the name `pyos*package` is not an acceptable name. However, the names `pyos_package` or `pyos-package` both are ok" +msgstr "" + +#: ../../tutorials/installable-code.md:176 +msgid "Hatch and project names" +msgstr "" + +#: ../../tutorials/installable-code.md:177 +msgid "Hatch makes some decisions for your project's name when you run `hatch new`" +msgstr "" + +#: ../../tutorials/installable-code.md:179 +msgid "These include using:" +msgstr "" + +#: ../../tutorials/installable-code.md:180 +msgid "dashes for the top level directory" +msgstr "" + +#: ../../tutorials/installable-code.md:181 +msgid "dashes for the project name in the pyproject.toml" +msgstr "" + +#: ../../tutorials/installable-code.md:182 +msgid "underscores for the package directory name" +msgstr "" + +#: ../../tutorials/installable-code.md:196 +msgid "If you use a name with underscores, Hatch will return the same thing:" +msgstr "" + +#: ../../tutorials/installable-code.md:209 +msgid "In both of the examples above the project name in the pyproject.toml file that hatch creates is `pyos-package`." +msgstr "" + +#: ../../tutorials/installable-code.md:213 +msgid "Next run:" +msgstr "" + +#: ../../tutorials/installable-code.md:228 +msgid "Your final project directory structure should look like this:" +msgstr "" + +#: ../../tutorials/installable-code.md:243 +msgid "Step 2: Add module to your package" +msgstr "" + +#: ../../tutorials/installable-code.md:245 +msgid "A Python module refers to a `.py` file containing the code that you want your package to access and run. Within the `pyospackage` subdirectory, add at least one Python modules (.py files)." +msgstr "" + +#: ../../tutorials/installable-code.md:247 +msgid "If you don't have code already and are just learning how to create a Python package, then create an empty `add_numbers.py` file. You will populate the `add_numbers.py` file with code provided below." +msgstr "" + +#: ../../tutorials/installable-code.md:250 +msgid "Python modules and the `__init__.py` file" +msgstr "" + +#: ../../tutorials/installable-code.md:254 +msgid "When you see the word module, we are referring to a `.py` file containing Python code." +msgstr "" + +#: ../../tutorials/installable-code.md:257 +msgid "The `__init__.py` allows Python to recognize that a directory contains at least one module that may be imported and used in your code. A package can have multiple modules[^python-modules]." +msgstr "" + +#: ../../tutorials/installable-code.md:261 +msgid "Your project directory should now look like this:" +msgstr "" + +#: ../../tutorials/installable-code.md:271 +msgid "Step 3: Add code to your module" +msgstr "" + +#: ../../tutorials/installable-code.md:273 +msgid "If you are following along and making a Python package from scratch then you can add the code below to your `add_numbers.py` module. The function below adds two integers together and returns the result. Notice that the code below has a few features that we will review in future tutorials:" +msgstr "" + +#: ../../tutorials/installable-code.md:275 +msgid "It has a [numpy-style docstring](numpy-docstring)" +msgstr "" + +#: ../../tutorials/installable-code.md:276 +msgid "It uses [typing](type-hints)" +msgstr "" + +#: ../../tutorials/installable-code.md:278 +msgid "Python can support many different docstrings formats depending on the documentation build system you wish to use. The most popular supported formats for documenting Python objects are NumPy Style Docstring[^numpydoc], Google Style Docstring[^googledoc], and the Epytext Style Docstrings[^epytextdoc]." +msgstr "" + +#: ../../tutorials/installable-code.md:280 +msgid "**pyOpenSci recommends using the NumPy Docstring convention.**" +msgstr "" + +#: ../../tutorials/installable-code.md:282 +msgid "If you aren't familiar with docstrings or typing yet, that is ok. You can review [this page in the pyOpenSci packaging guide](https://www.pyopensci.org/python-package-guide/documentation/write-user-documentation/document-your-code-api-docstrings.html) for an overview of both topics." +msgstr "" + +#: ../../tutorials/installable-code.md:311 +msgid "Step 4: Modify metadata in your `pyproject.toml` file" +msgstr "" + +#: ../../tutorials/installable-code.md:313 +msgid "Next, you will modify some of the metadata (information) that Hatch adds to your `pyproject.toml` file. You are are welcome to copy the file we have in our [example pyospackage GitHub repository](https://github.com/pyOpenSci/pyosPackage)." +msgstr "" + +#: ../../tutorials/installable-code.md:317 +msgid "Brief overview of the TOML file" +msgstr "" + +#: ../../tutorials/installable-code.md:320 +msgid "[The TOML format](https://toml.io/en/) consists of tables and variables. Tables are sections of information denoted by square brackets:" +msgstr "" + +#: ../../tutorials/installable-code.md:322 +msgid "`[this-is-a-table]`." +msgstr "" + +#: ../../tutorials/installable-code.md:324 +msgid "Tables can contain variables within them defined by an variable name and an `=` sign. For instance, a `build-system` table most often holds two (2) variables:" +msgstr "" + +#: ../../tutorials/installable-code.md:327 +msgid "`requires = `, which tells a build tool what tools it needs to install prior to building your package. In this case [hatchling](https://pypi.org/project/hatchling/)" +msgstr "" + +#: ../../tutorials/installable-code.md:329 +msgid "`build-backend = `, which is used to define the specific build-backend name, (in this example we are using `hatchling.build`)." +msgstr "" + +#: ../../tutorials/installable-code.md:338 +msgid "TOML organizes data structures, defining relationships within a configuration file." +msgstr "" + +#: ../../tutorials/installable-code.md:341 +msgid "[Learn more about the pyproject.toml format here.](../package-structure-code/pyproject-toml-python-package-metadata)" +msgstr "" + +#: ../../tutorials/installable-code.md:345 +msgid "You will learn more about the `pyproject.toml` format in the [next lesson when you add additional metadata / information to this file.](pyproject-toml.md)" +msgstr "" + +#: ../../tutorials/installable-code.md:348 +msgid "Open up the `pyproject.toml` file that Hatch created in your favorite text editor. It should look something like the example below." +msgstr "" + +#: ../../tutorials/installable-code.md:390 +msgid "Edit the file as follows:" +msgstr "" + +#: ../../tutorials/installable-code.md:392 +msgid "Delete `dynamic = [\"version\"]`: This sets up dynamic versioning based on tags stored in your git commit history. We will walk through implementing this in a later lesson." +msgstr "" + +#: ../../tutorials/installable-code.md:393 +msgid "Add `version = \"0.1\"` in the place of `dynamic = [\"version\"]` which you just deleted. This sets up manual versioning." +msgstr "" + +#: ../../tutorials/installable-code.md:394 +msgid "Fill in the description if it doesn't already exist." +msgstr "" + +#: ../../tutorials/installable-code.md:404 +msgid "Remove the `[tool.hatch.version]` table from the bottom of the file." +msgstr "" + +#: ../../tutorials/installable-code.md:412 +msgid "When this lesson exists, uncomment this admonition You will learn how to automate defining a package version using git tags in the version and release your package lesson." +msgstr "" + +#: ../../tutorials/installable-code.md:417 +msgid "OPTIONAL: Adjust project classifiers" +msgstr "" + +#: ../../tutorials/installable-code.md:419 +msgid "Hatch by default provides a list of classifiers that define what Python versions your package supports. These classifiers do not in any way impact your package's build and are primarily intended to be used when you publish your package to PyPI." +msgstr "" + +#: ../../tutorials/installable-code.md:424 +msgid "If you don't plan on publishing to PyPI, you can skip this section. However, if you wish, you can clean it up a bit." +msgstr "" + +#: ../../tutorials/installable-code.md:427 +msgid "To begin:" +msgstr "" + +#: ../../tutorials/installable-code.md:429 +msgid "Remove support for Python 3.8" +msgstr "" + +#: ../../tutorials/installable-code.md:430 +msgid "Within the `[project]` table, update `requires-python = \">3.8\"` to `requires-python = \">3.9\"`" +msgstr "" + +#: ../../tutorials/installable-code.md:432 +msgid "Since you are creating a pure Python package in this lesson, you can remove the following classifiers:" +msgstr "" + +#: ../../tutorials/installable-code.md:442 +msgid "Your new pyproject.toml file should now look something like this:" +msgstr "" + +#: ../../tutorials/installable-code.md:477 +msgid "The bare minimum needed in a pyproject.toml file" +msgstr "" + +#: ../../tutorials/installable-code.md:480 +msgid "The core information that you need in a `pyproject.toml` file in order to publish on PyPI is your **package's name** and the **version**. However, we suggest that you flesh out your metadata early on in the `pyproject.toml` file." +msgstr "" + +#: ../../tutorials/installable-code.md:482 +msgid "Once you have your project metadata in the pyproject.toml file, you will rarely update it. In the next lesson you'll add more metadata and structure to this file." +msgstr "" + +#: ../../tutorials/installable-code.md:486 +msgid "Step 5: Install your package locally" +msgstr "" + +#: ../../tutorials/installable-code.md:488 +msgid "At this point you should have:" +msgstr "" + +#: ../../tutorials/installable-code.md:490 +msgid "A project directory structure with a `pyproject.toml` file at the root" +msgstr "" + +#: ../../tutorials/installable-code.md:491 +msgid "A package directory containing an empty `__init__.py` file and" +msgstr "" + +#: ../../tutorials/installable-code.md:492 +msgid "At least one Python module (e.g. `add_numbers.py`)" +msgstr "" + +#: ../../tutorials/installable-code.md:494 +msgid "You are now ready to install (and build) your Python package!" +msgstr "" + +#: ../../tutorials/installable-code.md:496 +msgid "While you can do this using hatch, we are going to use pip for this lesson, so you can see how to install your tool into your preferred environment." +msgstr "" + +#: ../../tutorials/installable-code.md:498 +msgid "First open your preferred shell (Windows users may be using something like gitbash) and `cd` into your project directory if you are not already there." +msgstr "" + +#: ../../tutorials/installable-code.md:499 +msgid "Activate the Python environment that you wish to use." +msgstr "" + +#: ../../tutorials/installable-code.md:500 +msgid "Run `python -m pip install -e .`" +msgstr "" + +#: ../../tutorials/installable-code.md:503 +msgid "Add this back in when the lesson is published" +msgstr "" + +#: ../../tutorials/installable-code.md:504 +msgid "Activate the Python environment that you wish to use. If you need help with working with virtual environments check out this lesson (add link)." +msgstr "" + +#: ../../tutorials/installable-code.md:530 +msgid "What does `python -m pip install -e .` do?" +msgstr "" + +#: ../../tutorials/installable-code.md:533 +msgid "Let's break down `python -m pip install -e .`" +msgstr "" + +#: ../../tutorials/installable-code.md:535 +msgid "`python -m pip install -e .` installs your package into the current active Python environment in **editable mode** (`-e`). Installing your package in editable mode, allows you to work on your code and then test the updates interactively in your favorite Python interface. One important caveat of editable mode is that every time you update your code, you may need to restart Python." +msgstr "" + +#: ../../tutorials/installable-code.md:540 +msgid "If you wish to install the package regularly (not in editable mode) you can use:" +msgstr "" + +#: ../../tutorials/installable-code.md:543 +msgid "`python -m pip install . `" +msgstr "" + +#: ../../tutorials/installable-code.md:545 +msgid "**Using `python -m` when calling `pip`**" +msgstr "" + +#: ../../tutorials/installable-code.md:547 +msgid "Above, you use`python -m` to call the version of pip installed into your current active environment. `python -m` is important to ensure that you are calling the version of pip installed in your current environment." +msgstr "" + +#: ../../tutorials/installable-code.md:552 +msgid "Look for pyospackage in your environment" +msgstr "" + +#: ../../tutorials/installable-code.md:554 +msgid "Once you have installed your package, you can view it in your current environment. If you are using `venv` or `conda`, `pip` list will allow you to see your current package installations." +msgstr "" + +#: ../../tutorials/installable-code.md:558 +msgid "Note that because pyospackage is installed in editable mode (`-e`) pip will show you the directory path to your project's code" +msgstr "" + +#: ../../tutorials/installable-code.md:586 +msgid "Step 6: Test out your new package" +msgstr "" + +#: ../../tutorials/installable-code.md:588 +msgid "After installing your package, type “python” at the command prompt in your chosen terminal to start a Python session in your active Python environment." +msgstr "" + +#: ../../tutorials/installable-code.md:591 +msgid "You can now import your package and access the `add_num` function." +msgstr "" + +#: ../../tutorials/installable-code.md:603 +msgid "Installing packages from GitHub" +msgstr "" + +#: ../../tutorials/installable-code.md:605 +msgid "If you wish to share your code without publishing to PyPI you can always install packages directly from GitHub using the syntax:" +msgstr "" + +#: ../../tutorials/installable-code.md:612 +msgid "To make your package GitHub installable, you can:" +msgstr "" + +#: ../../tutorials/installable-code.md:614 +msgid "Create a new GitHub repository" +msgstr "" + +#: ../../tutorials/installable-code.md:615 +msgid "Push the contents of the project directory that you created above, to GitHub" +msgstr "" + +#: ../../tutorials/installable-code.md:616 +msgid "Finally install the package from GitHub using the command above. When you use the command above, don't forget to substitute the user, repo, and branch_or_tag with your specific values." +msgstr "" + +#: ../../tutorials/installable-code.md:618 +msgid "For instance below you install the pyospackage from the main branch of the pyOpenSci repository." +msgstr "" + +#: ../../tutorials/installable-code.md:621 +msgid "`python -m pip install git+https://github.com/user/repo.git@branch_or_tag`" +msgstr "" + +#: ../../tutorials/installable-code.md:625 +msgid "Congratulations! You created your first Python package" +msgstr "" + +#: ../../tutorials/installable-code.md:627 +msgid "You did it! You have now created a Python package that you can install into any Python environment." +msgstr "" + +#: ../../tutorials/installable-code.md:630 +msgid "In the upcoming lessons you will:" +msgstr "" + +#: ../../tutorials/installable-code.md:632 +msgid "Learn how to [build and publish your Python package to (test) PyPI](publish-pypi)" +msgstr "" + +#: ../../tutorials/installable-code.md:633 +msgid "Add a README file and LICENSE to your package" +msgstr "" + +#: ../../tutorials/installable-code.md:634 +msgid "Add more metadata to your `pyproject.toml` file to support PyPI publication." +msgstr "" + +#: ../../tutorials/installable-code.md:635 +msgid "learn how to publish to **conda-forge** from **PyPI**." +msgstr "" + +#: ../../tutorials/installable-code.md:637 +msgid "Add a [README file](add-readme.md) and [LICENSE](add-license-coc.md) to your package" +msgstr "" + +#: ../../tutorials/installable-code.md:638 +msgid "[Add more metadata to your `pyproject.toml`](pyproject-toml.md) file to support PyPI publication." +msgstr "" + +#: ../../tutorials/installable-code.md:639 +msgid "[Learn how to build your package distribution](publish-pypi) files (**sdist** and **wheel**) and publish to **test PyPI**." +msgstr "" + +#: ../../tutorials/installable-code.md:640 +msgid "Finally you will learn how to [publish to **conda-forge**](publish-conda-forge) from **PyPI**." +msgstr "" + +#: ../../tutorials/installable-code.md:644 +msgid "[Carpentries shell lesson](https://swcarpentry.github.io/shell-novice/)" +msgstr "" + +#: ../../tutorials/installable-code.md:646 +msgid "[Python module docs](https://docs.python.org/3/tutorial/modules.html#packages)" +msgstr "" + +#: ../../tutorials/installable-code.md:648 +msgid "[Numpy style docs](https://numpydoc.readthedocs.io/en/latest/format.html)" +msgstr "" + +#: ../../tutorials/installable-code.md:647 +msgid "[Google docstring style](https://google.github.io/styleguide/pyguide.html)" +msgstr "" + +#: ../../tutorials/installable-code.md:649 +msgid "[epydoc](https://epydoc.sourceforge.net/epytext.html)" +msgstr "" + +#: ../../tutorials/intro.md:28 +#: ../../tutorials/setup-py-to-pyproject-toml.md:24 +msgid "Get to know Hatch" +msgstr "" + +#: ../../tutorials/intro.md:28 +msgid "Python Packaging Tutorial Setup" +msgstr "" + +#: ../../tutorials/intro.md:35 +#: ../../tutorials/intro.md:80 +msgid "What is a Python package?" +msgstr "" + +#: ../../tutorials/intro.md:35 +msgid "Create a Python package" +msgstr "" + +#: ../../tutorials/intro.md:35 +msgid "Publish to PyPI" +msgstr "" + +#: ../../tutorials/intro.md:35 +msgid "Publish to conda-forge" +msgstr "" + +#: ../../tutorials/intro.md:35 +msgid "Create and publish a Python Package" +msgstr "" + +#: ../../tutorials/intro.md:45 +msgid "Add README file" +msgstr "" + +#: ../../tutorials/intro.md:45 +msgid "Add a license & code of conduct" +msgstr "" + +#: ../../tutorials/intro.md:45 +msgid "Update metadata in pyproject.toml" +msgstr "" + +#: ../../tutorials/intro.md:45 +msgid "Project information files & metadata" +msgstr "" + +#: ../../tutorials/intro.md:54 +msgid "Reference Guides" +msgstr "" + +#: ../../tutorials/intro.md:61 +msgid "Migrate setup.py to a pyproject.toml using Hatch" +msgstr "" + +#: ../../tutorials/intro.md:61 +msgid "Hatch for Existing Packages" +msgstr "" + +#: ../../tutorials/intro.md:2 +msgid "Python packaging 101" +msgstr "" + +#: ../../tutorials/intro.md:4 +msgid "_A start to finish beginner-friendly tutorial_" +msgstr "" + +#: ../../tutorials/intro.md:6 +msgid "Welcome to the pyOpenSci Python packaging tutorial series. The lessons on the upcoming pages walk you through the core steps needed to create a Python package." +msgstr "" + +#: ../../tutorials/intro.md:12 +msgid "Diagram showing the lessons in our packaging tutorial. There are 6 total - what is a Python package, make code pip installable, publish your package to PyPI, add a README and LICENSE file, add metadata for PyPI and finally publish to conda forge." +msgstr "" + +#: ../../tutorials/intro.md:14 +msgid "This lesson is the first in a series of lessons to help you get started with Python packaging." +msgstr "" + +#: ../../tutorials/intro.md:17 +msgid "Who are these tutorials for?" +msgstr "" + +#: ../../tutorials/intro.md:19 +msgid "The content in this tutorial series is beginner friendly and assumes that you have not created a Python package before. However, the content will still be valuable if you are interested in better understanding the steps involved in creating a Python package." +msgstr "" + +#: ../../tutorials/intro.md:24 +msgid "In this series you will learn about the core elements that you need to publish your package to the [Python Package Index (PyPI)](https://pypi.org/)." +msgstr "" + +#: ../../tutorials/intro.md:26 +msgid "In the second series, you will learn about infrastructure and documentation needed to support package maintenance." +msgstr "" + +#: ../../tutorials/intro.md:68 +#: ../../tutorials/publish-conda-forge.md:15 +#: ../../tutorials/publish-pypi.md:13 +#: ../../tutorials/pyproject-toml.md:19 +#: ../../tutorials/setup-py-to-pyproject-toml.md:12 +msgid "Learning Objectives" +msgstr "" + +#: ../../tutorials/intro.md:70 +msgid "This lesson introduces you to the basic components of a Python package. After reading this lesson you will:" +msgstr "" + +#: ../../tutorials/intro.md:73 +msgid "Understand what a Python package is" +msgstr "" + +#: ../../tutorials/intro.md:74 +msgid "Be able to list the 5 core components of a Python package" +msgstr "" + +#: ../../tutorials/intro.md:75 +msgid "Be able to explain the difference between generalizable code and code that supports a specific scientific application" +msgstr "" + +#: ../../tutorials/intro.md:82 +msgid "At a high level, you can think about a Python package as a toolbox that you can use to perform various tasks." +msgstr "" + +#: ../../tutorials/intro.md:85 +msgid "A Python package is basically a directory with a specific file structure. Within the package directory structure, there are modules which are files that end in `.py` (the same extension you'd see in a Python script). These modules allow you to group and structure your Python code. Each module contains functions and classes, that you can think about as the tools in your toolbox." +msgstr "" + +#: ../../tutorials/intro.md:94 +msgid "Diagram showing a sketch of a toolbox filled with different tools including a hammer and a saw." +msgstr "" + +#: ../../tutorials/intro.md:96 +msgid "You can think about a package as a toolbox filled with coding tools. A tool may be a function or a class. Each tool does a specific thing well." +msgstr "" + +#: ../../tutorials/intro.md:101 +msgid "Python packages are installable" +msgstr "" + +#: ../../tutorials/intro.md:103 +msgid "A package is installable, which means that you can add the functionality within the package's code to any Python environment and import that functionality like you would import core scientific Python packages such as NumPy or Matplotlib." +msgstr "" + +#: ../../tutorials/intro.md:112 +msgid "Installing a package into an environment makes it easier to manage and reuse your code across different projects. Structuring your code as a package is the first step you need to take so you can share the tools in the toolbox you've created and let others build with it." +msgstr "" + +#: ../../tutorials/intro.md:117 +msgid "Why create a Python package?" +msgstr "" + +#: ../../tutorials/intro.md:119 +msgid "You might create a Python package because you want to:" +msgstr "" + +#: ../../tutorials/intro.md:121 +msgid "**Use your code across different projects:** At its most basic level, creating a package allows you to install your code into a Python environment. This allows you to then import functions and classes into any workflows both locally and in the cloud." +msgstr "" + +#: ../../tutorials/intro.md:122 +msgid "**Share your code:** If you publish a package on a public repository such as PyPI or conda, your package can be installed on any machine using pip or conda with a single command." +msgstr "" + +#: ../../tutorials/intro.md:123 +msgid "**Build community around your code:** Packages make it easier for multiple people to work on the same project (particularly when published on GitHub). A version control system such as git (the system used by GitHub), further makes it easier to track changes to the codebase over time. Tools such as issues and pull requests make it easier for outside users to contribute bug fixes and to establish review processes for accepting changes to the code base." +msgstr "" + +#: ../../tutorials/intro.md:124 +msgid "**Organize your code:** Packages can be used to organize large code projects, dividing them into smaller, more manageable components. This structure can help with both maintaining the codebase and with making it easier to understand." +msgstr "" + +#: ../../tutorials/intro.md:126 +msgid "What to consider before you create a package" +msgstr "" + +#: ../../tutorials/intro.md:128 +msgid "Creating a Python package that others use takes considerable time and effort. Before you begin, think about your goals including:" +msgstr "" + +#: ../../tutorials/intro.md:131 +msgid "Who you think will use your package" +msgstr "" + +#: ../../tutorials/intro.md:132 +msgid "How people might use your package and on what data (if data are relevant)" +msgstr "" + +#: ../../tutorials/intro.md:133 +msgid "Whether you have time to add things such as documentation and tests" +msgstr "" + +#: ../../tutorials/intro.md:134 +msgid "How long you might be able to maintain it: remember that once people begin using your package they will depend on your maintainer team to update it, fix bugs and answer questions." +msgstr "" + +#: ../../tutorials/intro.md:136 +msgid "Before creating a user-facing package, it's important to consider all of the above." +msgstr "" + +#: ../../tutorials/intro.md:138 +msgid "The elements of a Python package" +msgstr "" + +#: ../../tutorials/intro.md:142 +#: ../../tutorials/intro.md:220 +msgid "Diagram showing .. more here if this stays." +msgstr "" + +#: ../../tutorials/intro.md:144 +msgid "The elements of a Python package include code, documentation, tests, an OSI-approved license and infrastructure. Maintainers are at the core making sure everything works and is up to date while fixing bugs and addressing user concerns." +msgstr "" + +#: ../../tutorials/intro.md:150 +msgid "The core elements of Python package include:" +msgstr "" + +#: ../../tutorials/intro.md:152 +msgid "**Code:** Functions and classes that provide functionality for a user of your package" +msgstr "" + +#: ../../tutorials/intro.md:153 +msgid "**Documentation:** Installation instructions, tutorials, and examples that both help users get started using your package and contributors and maintainers fix bugs and maintain the package." +msgstr "" + +#: ../../tutorials/intro.md:154 +msgid "Contributor Documentation in the form of a **CONTRIBUTING.md** file is useful to help people to contribute to your package." +msgstr "" + +#: ../../tutorials/intro.md:155 +msgid "Development Documentation helps both maintainers and contributors understand how to maintain a package's infrastructure." +msgstr "" + +#: ../../tutorials/intro.md:156 +msgid "**Tests:** that make sure your code works as it should and makes it easier for you and others to contribute to, modify and update the code in the future" +msgstr "" + +#: ../../tutorials/intro.md:157 +msgid "**License:** An open source license, or license that is [OSI approved](https://opensource.org/licenses/), refers to an license that allows others to use your package. It also provides legal direction regarding how elements of the package can and can't be reused." +msgstr "" + +#: ../../tutorials/intro.md:158 +msgid "**Infrastructure** that automates updates, publication workflows and runs test suites. Infrastructure includes a suite of things such as platforms like GitHub and GitLab, tools to run tests and tools locally such as nox and tox and continuous integration that automates package maintenance steps." +msgstr "" + +#: ../../tutorials/intro.md:160 +msgid "What pyOpenSci looks for in a package" +msgstr "" + +#: ../../tutorials/intro.md:163 +msgid "pyOpenSci performs an [initial set of editor checks](https://www.pyopensci.org/software-peer-review/how-to/editor-in-chief-guide.html#editor-checklist-template) for any package submitted to us for peer review. You may find these checks useful as you create your package as a baseline for things that you package should have." +msgstr "" + +#: ../../tutorials/intro.md:169 +msgid "Packages are more than just code - Infrastructure" +msgstr "" + +#: ../../tutorials/intro.md:171 +msgid "A package in any language is more than just code. If you expect other people to use your package, besides yourself, you should consider not only writing high quality code, but also the various elements of a package that make it a useful community resource." +msgstr "" + +#: ../../tutorials/intro.md:176 +msgid "Version control and storing your package on GitHub or GitLab" +msgstr "" + +#: ../../tutorials/intro.md:178 +msgid "Most Python packages live in an online version control platform such as GitHub or GitLab. GitHub and GitLab both run [git](https://git-scm.com/) for version control. Having your software under version control is important because it allows you to both track changes over time while also going back in history and undoing changes in the case that a change to the code base unexpectedly breaks something." +msgstr "" + +#: ../../tutorials/intro.md:183 +msgid "By publishing your package on GitHub or GitLab, you are making your code public facing. This means that others can both see your code and also make contributions using a pull request (GitHub) / merge request (GitLab) / code review workflow." +msgstr "" + +#: ../../tutorials/intro.md:185 +msgid "GitHub & GitLab vs. Git" +msgstr "" + +#: ../../tutorials/intro.md:188 +msgid "GitHub and GitLab are online (cloud) platforms that run `git` (version control software) on the backend. Running git locally on your computer allows you to upload (`git push`) and download (`git pull`) files to GitHub and GitLab." +msgstr "" + +#: ../../tutorials/intro.md:193 +msgid "Issues or Ticket Trackers" +msgstr "" + +#: ../../tutorials/intro.md:195 +msgid "GitHub and GitLab also both offer community features such as issues that allow:" +msgstr "" + +#: ../../tutorials/intro.md:197 +msgid "you to communicate with your maintainers and contributor community" +msgstr "" + +#: ../../tutorials/intro.md:198 +msgid "users to report bugs, ask questions and request new features" +msgstr "" + +#: ../../tutorials/intro.md:199 +msgid "you to publicly keep track of enhancements and features you want to work on for your package." +msgstr "" + +#: ../../tutorials/intro.md:201 +msgid "Continuous integration and continuous deployment" +msgstr "" + +#: ../../tutorials/intro.md:203 +msgid "GitHub and GitLab also provide continuous integration and continuous deployment (CI/CD). Continuous integration (CI) refers to a platform that automatically runs a specific job when a certain event occurs, whereas continuous deployment (CD) is an extension of CI that refers to not only running or building but also to publishing the final outputs somewhere." +msgstr "" + +#: ../../tutorials/intro.md:205 +msgid "**An example of Continuous integration:**" +msgstr "" + +#: ../../tutorials/intro.md:207 +msgid "When someone submits a change to your code, your tests will run across different operating systems and the code will be checked for format issues." +msgstr "" + +#: ../../tutorials/intro.md:209 +msgid "**An example of Continuous deployment:**" +msgstr "" + +#: ../../tutorials/intro.md:211 +msgid "When you are ready to release your package to PyPI, a continuous deployment operation might be triggered on release to publish your package to PyPI." +msgstr "" + +#: ../../tutorials/intro.md:213 +msgid "Integrated CI/CD will help you maintain your software, ensuring that changes to the code don't break things unexpectedly. They can also help you maintain code style and format consistency for every new change to your code." +msgstr "" + +#: ../../tutorials/intro.md:222 +msgid "The lifecycle of a scientific Python package." +msgstr "" + +#: ../../tutorials/intro.md:225 +msgid "When should you turn your code into a Python package?" +msgstr "" + +#: ../../tutorials/intro.md:227 +msgid "You may be wondering, what types of code should become a Python package that is both on GitHub and published to PyPI and/or conda-forge." +msgstr "" + +#: ../../tutorials/intro.md:229 +msgid "There are a few use cases to consider:" +msgstr "" + +#: ../../tutorials/intro.md:231 +msgid "**Creating a basic package for yourself:** Sometimes you want create a package for your own personal use. This might mean making your code locally pip installable and you may also want to publish it to GitHub. In that case you don't expect others to use your code, and as such you may only have documentation for you and your future self if you need to update the package." +msgstr "" + +#: ../../tutorials/intro.md:233 +msgid "An example of this type of package might be a set of functions that you write that are useful across several of your projects. It could be useful to have those functions available to all of your projects." +msgstr "" + +#: ../../tutorials/intro.md:236 +msgid "LINK to pip installable lesson when it's published - it's in review now" +msgstr "" + +#: ../../tutorials/intro.md:239 +msgid "**Creating a package for the community:** In other cases, you may create some code that you soon realize might also be useful to not just you, but to other people as well. In that case, you might consider both creating the package, publishing it on GitHub, and because other users may be using it, you may make use of GitHub's infrastructure including CI/CD pipelines and issue trackers. Because you want other people to use your package, you will want to also include LICENSE information, documentation for users and contributors and tests. This type of package is most often published to PyPI." +msgstr "" + +#: ../../tutorials/intro.md:242 +msgid "For example, all of the [pyOpenSci packages](https://www.pyopensci.org/python-packages.html) are public facing with an intended audience beyond just the maintainers." +msgstr "" + +#: ../../tutorials/intro.md:244 +msgid "Packages that you expect others to use should be well-scoped" +msgstr "" + +#: ../../tutorials/intro.md:246 +msgid "Ideally the code in your Python package is focused on a specific theme or use case. This theme is important as it's a way to scope the content of your package." +msgstr "" + +#: ../../tutorials/intro.md:248 +msgid "It can be tricky to decide when your code becomes something that might be more broadly useful to others. But one question you can ask yourself is - is your code written specifically for a single research project? Or could it have a broader application across multiple projects in your domain?" +msgstr "" + +#: ../../tutorials/intro.md:250 +msgid "How does this relate to code for a research project?" +msgstr "" + +#: ../../tutorials/intro.md:253 +msgid "A [Research Compendium](https://the-turing-way.netlify.app/reproducible-research/compendia.html) is an organized set of code, data and documentation that supports a specific research project. It aims to enhance the reproducibility and transparency of research by providing a comprehensive record of the methods, data, and analyses used in a study." +msgstr "" + +#: ../../tutorials/intro.md:258 +msgid "A Python package is a collection of modules that can be used to perform a specific set of tasks. These tasks should be applicable to numerous workflows. As such a Python package is more generalizable than a Research Compendium which supports a specific project." +msgstr "" + +#: ../../tutorials/intro.md:263 +msgid "[Read about `Good enough practices in scientific computing`](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1005510)" +msgstr "" + +#: ../../tutorials/intro.md:264 +msgid "[Learn more about research compendia (also called repo-packs) in this blog post.](https://lorenabarba.com/blog/how-repro-packs-can-save-your-future-self/)" +msgstr "" + +#: ../../tutorials/intro.md:267 +msgid "Below are a few examples well scoped pyOpenSci packages:" +msgstr "" + +#: ../../tutorials/intro.md:269 +msgid "[Crowsetta](https://crowsetta.readthedocs.io/en/latest/): is a package designed to work with annotating animal vocalizations and bioacoustics data. This package helps scientists process different types of bioacoustic data rather than focusing on a specific individual research application associated with a user-specific research workflow." +msgstr "" + +#: ../../tutorials/intro.md:270 +msgid "[Pandera](https://www.union.ai/pandera) is another more broadly used Python package. Pandera supports data testing and thus also has a broader research application." +msgstr "" + +#: ../../tutorials/intro.md:272 +msgid "Matplotlib as an example" +msgstr "" + +#: ../../tutorials/intro.md:274 +msgid "At the larger end of the user spectrum, Matplotlib is a great example. Matplotlib does one thing really well:" +msgstr "" + +#: ../../tutorials/intro.md:277 +msgid "_It creates visual plots of data._" +msgstr "" + +#: ../../tutorials/intro.md:279 +msgid "Thousands of people use Matplotlib for different plotting applications using different types of data. While few scientific packages will have the same broad application and large user base that Matplotlib has, the idea of scoping out what your package does is still important." +msgstr "" + +#: ../../tutorials/intro.md:285 +msgid "Code should also be clean & readable & documented" +msgstr "" + +#: ../../tutorials/intro.md:287 +msgid "The code in your package should also be clean, readable, and well documented." +msgstr "" + +#: ../../tutorials/intro.md:289 +msgid "**Clean code:** Clean code refers to code that uses expressive variable names, is concise and doesn't repeat itself. You can learn about best practices for clean code in future pyOpenSci tutorials." +msgstr "" + +#: ../../tutorials/intro.md:293 +msgid "**Readable code:** readable code is code written with a consistent style. You can use linters and code formatters such as black and flake8 to ensure this consistency throughout your entire package. [Learn more about code formatters here.](../package-structure-code/code-style-linting-format)" +msgstr "" + +#: ../../tutorials/intro.md:297 +msgid "**Documented code:** documented code is written using docstrings that help a user understand both what the functions and methods in your code do and also what the input and output elements of each function are. [You can learn more about docstrings in our guide, here.](../documentation/write-user-documentation/document-your-code-api-docstrings)" +msgstr "" + +#: ../../tutorials/intro.md:301 +msgid "Making your package installable - publishing to PyPI & conda-forge" +msgstr "" + +#: ../../tutorials/intro.md:303 +msgid "Python packages and environments" +msgstr "" + +#: ../../tutorials/intro.md:305 +msgid "You can install a Python package into a Python environment in the same way you might install NumPy or Pandas. Installing your package into an environment allows you to access it from any code run with that specific Python environment activated." +msgstr "" + +#: ../../tutorials/intro.md:311 +msgid "Diagram showing the steps associated with creating a package and then installing it. The first arrow says your package and the second says pip install package. The second arrow leads to a box that represents a Python environment that already has some packages installed such as Pandas and NumPy. Your package will also get installed into that same environment when you pip install it." +msgstr "" + +#: ../../tutorials/intro.md:313 +msgid "You don't have to publish to PyPI to make your code installable. With the correct file structure and project metadata you can make your code installable locally on your computer and use it for projects that you are working on without having to ever publish to PyPI. Publishing to PyPI is useful when you want to make your code public-facing and share it with others." +msgstr "" + +#: ../../tutorials/intro.md:320 +msgid "Publishing a package to PyPI / Conda-Forge" +msgstr "" + +#: ../../tutorials/intro.md:322 +msgid "If you want to make your package directly installable without having to download the code to your computer locally then you need to publish it in a repository such as **PyPI** or **conda-forge**." +msgstr "" + +#: ../../tutorials/intro.md:326 +msgid "Learn [how to publish your package to PyPI in this tutorial.](publish-pypi.md)" +msgstr "" + +#: ../../tutorials/intro.md:328 +msgid "Then you can create a conda-forge recipe using the [Grayskull](https://github.com/conda/grayskull) tool. You can then submit this recipe to conda-forge." +msgstr "" + +#: ../../tutorials/intro.md:330 +msgid "[You will learn more about the conda-forge publication process here.](publish-conda-forge.md)" +msgstr "" + +#: ../../tutorials/intro.md:333 +msgid "Graphic showing the high level packaging workflow. On the left you see a graphic with code, metadata and tests in it. Those items all go into your package. Documentation and data are below that box because they aren't normally published in your packaging wheel distribution. An arrow to the right takes you to a build distribution files box. That box leads you to either publishing to TestPyPI or the real PyPI. From PyPI you can then connect to conda-forge for an automated build that sends distributions from PyPI to conda-forge." +msgstr "" + +#: ../../tutorials/intro.md:335 +msgid "In the image above, you can see the steps associated with publishing your package on PyPI and conda-forge. Note that the distribution files that PyPI requires are the [sdist](#python-source-distribution) and [wheel](#python-wheel) files. Once you are ready to make your code publicly installable, you can publish it on PyPI. Once your code is on PyPI it is straight forward to then publish to conda-forge. You create a recipe using the Grayskull package and then you open a pr in the conda-forge recipe repository. You will learn more about this process in the [conda-forge lesson](/tutorials/publish-conda-forge)." +msgstr "" + +#: ../../tutorials/intro.md:339 +msgid "Yay, your package has users! Now what?" +msgstr "" + +#: ../../tutorials/intro.md:341 +msgid "As the community using your package grows, you may also find yourself managing users, contributors, and others who want to interact with your package. It’s important to consider all this before you dive into development. Once you have a user base in the community, people will depend upon your code to work and will need direction regarding how to use it." +msgstr "" + +#: ../../tutorials/intro.md:343 +msgid "To support your community, you'll want to add things like:" +msgstr "" + +#: ../../tutorials/intro.md:345 +msgid "[a development guide that documents your maintainer workflow process ](/documentation/repository-files/development-guide.md)" +msgstr "" + +#: ../../tutorials/intro.md:346 +msgid "[a code of conduct to defines community interaction standards and expectations](/documentation/repository-files/code-of-conduct-file.md)" +msgstr "" + +#: ../../tutorials/intro.md:347 +msgid "[a contributing guide that helps users understand expectations associated with making contributions to your project](/documentation/repository-files/contributing-file.md)" +msgstr "" + +#: ../../tutorials/intro.md:349 +msgid "Support for contributors and maintainers" +msgstr "" + +#: ../../tutorials/intro.md:351 +msgid "If you intend for others to use and contribute to your code, consider who will maintain it over time. You will want a **contributing and development** guide to help new potential contributors get started with contributing to your package, as well as a **code of conduct** to ensure community interactions remain healthy both for you and your contributors and maintainer team." +msgstr "" + +#: ../../tutorials/intro.md:353 +msgid "The elements above are also important for future maintenance of your package. In the case that you are no long able to maintain it or simply want extra help, development, and contributing documentation will help you onboard new maintainers." +msgstr "" + +#: ../../tutorials/intro.md:358 +msgid "What's next?" +msgstr "" + +#: ../../tutorials/intro.md:360 +msgid "In future lessons you will learn more about the infrastructure around a published Python package that makes it both easier to maintain, easier for others to contribute to and easier for other scientists to use. However, first we want to get you to your initial goal of publishing a Python package." +msgstr "" + +#: ../../tutorials/intro.md:362 +msgid "In this next lesson you will learn how to create a basic installable Python package. Make your code pip installable " +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:1 +msgid "Publish your Python package that is on PyPI to conda-forge" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:3 +msgid "In the previous lessons, you've learned:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:5 +msgid "How to [create the most basic version of a Python package](installable-code.md). This entailed making your code installable." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:6 +msgid "[How to publish your Python package to PyPI](publish-pypi)" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:7 +msgid "How to add a `README` and `LICENSE` file to your package" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:8 +msgid "How to setup your `pyproject.toml` file with all of the metadata that PyPI requires and also metadata that will be helpful for users to find your package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:10 +msgid "If you have gone through all of the above lessons, you are now ready to publish your package on conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:13 +msgid "**IMPORTANT:** Please do not practice publishing your package to conda-forge. You should only publish to conda-forge when you have a package on pypi.org that you plan to maintain." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:19 +#: ../../tutorials/publish-pypi.md:17 +msgid "In this lesson you will learn how to:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:21 +msgid "Create a conda-forge yaml recipe for your package using Grayskull" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:22 +msgid "Submit the recipe (yaml file) to the conda-forge staged recipes repository as a pull request" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:23 +msgid "Maintain your conda-forge package by creating new releases for your package on PyPI" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:26 +msgid "Once your package is on PyPI you can then easily publish it to conda-forge using the [grayskull](https://conda.github.io/grayskull/) tool. You do not need to build the package specifically for conda, conda-forge will build from your PyPI source distribution file (sdist)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:33 +msgid "Image showing the progression of creating a Python package, building it and then publishing to PyPI and conda-forge. You take your code and turn it into distribution files (sdist and wheel) that PyPI accepts. Then there is an arrow towards the PyPI repository where ou publish both distributions. From PyPI if you create a conda-forge recipe you can then publish to conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:35 +msgid "Once you have published both package distributions (the source distribution and the wheel) to PyPI, you can then publish to conda-forge. Conda-forge requires a source distribution on PyPI in order to build your package on conda-forge. You do not need to rebuild your package to publish to conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:38 +msgid "What is conda-forge?" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:40 +msgid "conda is an open source package and environment management tool that can be used to install tools from the different channels on Anaconda.org." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:43 +msgid "You can think about a channel as a specific location where a group of packages are stored and can be installed from using a command such as `conda install packagename`. In the case of conda channels, some of these channels such as the `defaults` channel, is managed by Anaconda (the company). Only Anaconda can decide what packages are available in the `defaults` channel. However, the conda-forge (and bioconda) channel are community-managed channels. Anyone can submit a package to these channels however they must pass a technical review in the [staged-recipes GitHub repository](https://github.com/conda-forge/staged-recipes) to be published." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:46 +msgid "[Learn more about conda channels here.](#about-conda)" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:50 +msgid "Graphic with the title Python package repositories. Below it says anything hosted on PyPI can be installed using pip install. Packaging hosted on a conda channel can be installed using conda install. Below that there are two rows. The top row says conda channels. Next to it are three boxes one with conda-forge, community maintained; bioconda and then default - managed by the Anaconda team. Below that there is a row that says PyPI servers. PyPI - anyone can publish to PyPI and test PyPI (a testbed server for you to practice)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:52 +msgid "Conda channels represent various repositories that you can install packages from. Because conda-forge is community maintained, anyone can submit a recipe there. PyPI is also a community maintained repository. Anyone can submit a package to PyPI and test PyPI. Unlike conda-forge there are no manual checks of packages submitted to PyPI." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:55 +msgid "Why publish to conda-forge" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:57 +msgid "There are many users, especially in the scientific Python ecosystem that use conda as their primary package manager / environment tool. Thus, having packages available to these users on the conda-forge channel is useful. In some cases packages on conda-forge can minimize dependency conflicts that can occur when mixing installations using pip and conda. This is particularly important for the spatial ecosystem." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:59 +msgid "How publishing to conda-forge works" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:61 +msgid "Once you have built and published your package to PyPI, you have everything that you need to publish to conda-forge. There is no additional build step needed to publish to conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:63 +msgid "Conda-forge will build your package from the source distribution which you [published to PyPI in the previous lesson](publish-pypi) using the recipe that you will create below." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:65 +msgid "Conda-forge publication steps" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:68 +msgid "Image showing the steps associated with publishing to conda-forge. Check out the caption below for a detailed description." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:70 +msgid "The steps for publishing to conda-forge begin with publishing your Python package to PyPI. Once you have published to PyPI you can then create a yaml file recipe that can be submitted to the conda-forge staged recipes repository for review. Once that recipe is accepted, your package will get it's on repository (known as a feedstock) on conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:73 +msgid "The steps to publish to conda-forge are:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:75 +msgid "Publish your Python package distribution files (sdist & wheel) to PyPI" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:76 +msgid "Create a conda-forge recipe, which is a yaml file with instructions on how to build your package on conda-forge, using the grayskull[^grayskull] package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:77 +msgid "Submit the recipe (yaml file) to the conda-forge staged recipes repository as a pull request for review. [Click here for an example submission from pyOpenSci.](https://github.com/conda-forge/staged-recipes/pull/25173)" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:79 +msgid "Once someone from the conda-forge team reviews your pull request, you may need to make some changes. Eventually the pull request will be approved and merged." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:81 +msgid "Once your recipe is accepted and merged on conda-forge, users can install your package using:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:83 +msgid "`conda install -c conda-forge your-package`" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:85 +msgid "You only create the recipe once. Once the recipe is accepted and merged, you only need to maintain the repository." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:87 +msgid "Maintaining a conda-forge package" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:89 +msgid "Once your package is on conda-forge, the repository will track release activity on the package's PyPI repository. Any time you make a new PyPI release with a new source distribution, conda-forge will build and update your conda-forge repository (also known as a feedstock)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:91 +msgid "When the update is processed, the friendly conda-forge bot will create a new pull request with an updated distribution recipe in your feedstock." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:93 +msgid "You can review that pull request and then merge it once all of the continuous integration tests pass." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:95 +msgid " How to Publish your package on conda-forge" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:97 +msgid "It's time to add your package to the conda-forge channel. Remember that your package needs to be on PyPI before the steps below will work. And also remember that the team managing conda-forge are all volunteers." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:100 +msgid "Be sure that your package is on PyPI.org (not test.pypi.org) before you attempt to publish to conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:103 +msgid "Only submit your package to conda-forge if you intend to maintain it over time." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:106 +msgid "Note - this is a tutorial aimed to help you get your package onto conda-forge. The official conda documentation for this processed [is here](https://conda-forge.org/docs/maintainer/adding_pkgs.html)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:108 +msgid "Step 1: Install grayskull" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:110 +msgid "First, [install grayskull](https://conda.github.io/grayskull/user_guide.html). You can install it using either pip:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:116 +msgid "or conda" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:122 +msgid "To run this command, use the same shell / terminal that you have been using to run hatch commands in the previous tutorials." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:127 +msgid "You can also install grayskull using pipx[^pipx]. pipx is a tool that allows you to install commonly used tools that you might want to have available across multiple Python environments rather than installing the package into every Python environment that you create." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:130 +msgid "Step 2: Fork and clone the conda-forge staged-recipes repository" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:132 +msgid "Next, open your shell and `cd` to a location where you want to clone the **conda-forge/staged-recipes** repository." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:133 +msgid "fork and clone the [conda-forge/staged-recipes GitHub repository](https://github.com/conda-forge/staged-recipes)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:134 +msgid "Create a new branch in your fork rather than submitting from the main branch of your fork. We suggest naming the branch your package's name." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:136 +msgid "`git checkout -b your-package-name `" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:138 +msgid "In bash, `cd` into the `staged-recipes/recipes` folder" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:146 +msgid "Next, create a new branch in your `conda-forge/staged-recipes` cloned repository. You might want to make that branch the same name as your package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:157 +msgid "Step 3: Create your conda-forge recipe" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:159 +msgid "Next, navigate to the recipes directory" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:161 +msgid "If you run `ls` here, you will notice there is an example directory with an example recipe for you to look at." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:173 +msgid "Next, run `grayskull pypi your-package-name` to generate a recipe." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:217 +msgid "Grayskull will pull metadata about your package from PyPI. It does not use your local installation of the package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:218 +msgid "An internet connection is needed to run the `grayskull pypi your-package-name` step." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:221 +msgid "When you run grayskull, it will grab the latest distribution of your package from PyPI and will use that to create a new recipe." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:223 +msgid "The recipe will be saved in a directory named after your package's name, wherever you run the command." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:225 +msgid "`recipes/packagename/meta.yaml`" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:227 +msgid "At the very bottom of the grayskull output, it will also tell you where it saved the recipe file." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:230 +msgid "Open the meta.yaml file. The finished `meta.yaml` file that grayskull creates should look like the example below:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:277 +msgid "Step 3b: Bug fix - add a home url to the about: section" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:279 +msgid "There is currently a small bug in Grayskull where it doesn't populate the home: element of the recipe. If you don't include this, [you will receive an error message](https://github.com/conda-forge/staged-recipes/pull/25173#issuecomment-1917916528) from the friendly conda-forge linter bot." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:293 +msgid "to fix this, open your meta.yaml file in your favorite text editor." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:294 +msgid "and add a home: element to the about section" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:296 +msgid "The about section will look like this after you create your recipe." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:306 +msgid "Below you add a home: element. If you have a project home page / website you can use that url. Otherwise, you can also use your PyPI landing page." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:317 +msgid "Step 4: tests for conda-forge" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:319 +msgid "Next, have a look at the tests section in your **meta.yaml** file. At a minimum you should import your package or the main modules associated with your package and run `pip check`." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:321 +msgid "`pip check` will ensure that your package installs properly with all of the proper dependencies." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:333 +msgid "If you have more advanced tests that you wish to run, you can add them here. However, you can also simply leave the tests section as it is." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:335 +msgid "Step 4: Submit a pull request to the staged-recipes repository" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:337 +msgid "Once you have completed all of the above, you are ready to open up a pull request in the `conda-forge/staged-recipes repository`." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:339 +msgid "Submit a pull request from your fork/branch of the staged-recipes repository." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:340 +msgid "Remember that the conda-forge maintainers are volunteers. Be patient for someone to respond and supportive in your communication with them." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:0 +msgid "Conda-forge checklist help" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:346 +msgid "Conda-forge Staged-recipes Pull Request Checklist" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:348 +msgid "When you submit your package to conda-forge, the pull request template includes a list of checks that you want to ensure you have covered." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:350 +msgid "Below we break down each element of that list." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:352 +msgid "Pull request template checklist tips" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:355 +msgid "-[x] Title of this PR is meaningful: e.g. \"Adding my_nifty_package\", not \"updated meta.yaml\"." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:357 +msgid "**Translation:** Make sure that your pull request title is specific. We suggest something like: `Add recipe for `" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:360 +msgid "-[x] License file is packaged (see [here](https://github.com/conda-forge/staged-recipes/blob/5eddbd7fc9d1502169089da06c3688d9759be978/recipes/example/meta.yaml#L64-L73) for an example)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:362 +msgid "**Translation:** You should have a LICENSE file included in your package's source distribution. If you have followed the pyOpenSci tutorials then you already have a LICENSE file and are likely using the MIT license. When you run `hatch build`, it will bundle that file into the output [source distribution file (which is the tar.gz file)](python-source-distribution) that conda-forge will use to build your package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:364 +msgid "[x] Source is from official source." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:366 +msgid "**Translation:** If your package is on PyPI as you learned in the [previous lesson on publishing your Python package](publish-pypi) then you are in good shape. conda-forge prefers that your distribution is published to a known repository." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:368 +msgid "-[x] Package does not vendor other packages. (If a package uses the source of another package, they should be separate packages or the licenses of all packages need to be packaged)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:370 +msgid "**Translation:** If the code base in your package is your own and it all shares the same LICENSE then you are in good shape. If you have code taken from other packages then you may need to declare that and include licenses for that code if it is different. If you followed these tutorials then you do not have any vendored code." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:372 +msgid "-[x] If static libraries are linked in, the license of the static library is packaged." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:374 +msgid "-[x] Package does not ship static libraries. If static libraries are needed, [follow CFEP-18](https://github.com/conda-forge/cfep/blob/main/cfep-18.md)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:376 +msgid "**Translation:** A static library refers to a copy of a package built into your package. If your package is a pure Python package, then you can check that your package does not ship static libraries as this does not apply to you." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:378 +msgid "The pyOpenSci tutorials are all pure Python and as such do not use static libraries in a linked or shipped (included in the package distribution) format." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:380 +msgid "If your package has a more complex build that includes links to extensions written in other languages such as C++, then be sure to include the proper licenses for those extensions in your metadata." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:385 +msgid "If you want to learn more about static libraries, then [this overview](https://pypackaging-native.github.io/background/compilation_concepts/#shared-vs-static-libraries) might help." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:388 +msgid "-[ ] Build number is 0." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:390 +msgid "**Translation:** The build number in your recipe is right below the source location of your package's source distribution. `number: 0` is what you should see in that section of your recipe." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:403 +msgid "[x] A tarball (`url`) rather than a repo (e.g. `git_url`) is used in your recipe (see [here](https://conda-forge.org/docs/maintainer/adding_pkgs.html) for more details)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:405 +msgid "**Translation:** Here conda wants you to provide a link to the source distribution on PyPI rather than a link to your GitHub repository distribution. Notice above in the Source section of your recipe there is a `url:` section that provides a PyPI url that ends in tar.gz. That is a link to your source distribution that conda-forge will use." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:411 +msgid "[x] GitHub users listed in the maintainer section have posted a comment confirming they are willing to be listed there." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:413 +msgid "**Translation** Once you have submitted your recipe, be sure that all maintainers listed in your recipe respond acknowledging that they are ok with being listed as a maintainer for the conda-forge version of your package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:415 +msgid "[x] When in trouble, please check our [knowledge base documentation](https://conda-forge.org/docs/maintainer/knowledge_base.html) before pinging a team." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:417 +msgid "**Translation** The conda team are volunteers who spend their time supporting our community. Please try to troubleshoot on your own first before tagging one of them for help." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:419 +msgid "This is also why we don't suggest you publish to conda-forge as a practice run." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:423 +msgid "Once you create your pull request, a suite of CI actions will run that build and test the build of your package. A conda-forge maintainer will work with you to get your recipe in good shape and merged." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:427 +msgid "Image showing the 5 CI tasks that will run against your package in the GitHub interface after you'ce created a pull request." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:429 +msgid "Wait until all of the CI steps in your pull request have run. At that point your pull request is ready for review by a conda-forge maintainer." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:432 +msgid "In some cases getting all of the checks to run successfully in CI might take a bit of work. If you are struggling to get your recipe to build properly, you can ping the conda-forge maintainer team for help." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:434 +msgid "Please be patient and wait for them to respond." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:436 +msgid "conda-forge staged recipes and CI failures" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:439 +msgid "If your package is a pure Python package that can be installed on any type of computer (Windows, mac, linux) and has no architecture requirements (known as noarch: Python or no architecture requirements) then the conda-forge team only requires tests for Linux CI to pass." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:441 +msgid "So if tests for Windows and MAC OS fail, that is to be expected. In this case, don't worry about failing tests, the maintainer team can help you get your package published." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:444 +msgid "Once you have submitted your recipe, you can wait for the CI build to pass. If it's not passing, and you aren't sure why, a conda-forge maintainer can likely help you figure things out." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:446 +msgid "Once your recipe is built and merged, the conda team will create a new package repository for you similar to [this one for the GemGIS package](https://github.com/conda-forge/gemgis-feedstock)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:448 +msgid " Congratulations - you have added your package to conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:450 +msgid "The last part of this process is maintaining the repository. We cover that next." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:453 +msgid "Maintaining your conda-forge feedstock" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:455 +msgid "Every time you create a new release on PyPI, the conda-forge bots will recognize the release and will rebuild the newly released version of your package. This process may take a day or two to complete so be patient." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:457 +msgid "Once the conda-forge build is complete, all of the maintainers of your conda-forge feedstock will get a ping on GitHub that a new pull request has been opened." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:459 +msgid "Review the pull request. If all tests are passing, you can merge it. Shortly after merging your pull request, the conda-forge release will be available for users to install:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:461 +msgid "`conda install -c conda-forge yourpackage`" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:465 +msgid "If you have walked through this entire tutorial series you will now:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:467 +msgid "Understand [what a Python package is ](intro.md)" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:468 +msgid "Know how to [make your code installable](installable-code.md) into Python environments" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:469 +msgid "Know how to create a `pyproject.toml` file, a `README` file, and a `LICENSE` and code of conduct." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:470 +msgid "Know how to [publish your package to PyPI](publish-pypi.md) and" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:471 +msgid "Know how to publish your package to conda-forge" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:473 +msgid "The above are the basic steps that you need to take to create and publish a Python package. In a future tutorial series we will cover that basics of maintaining your package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:477 +msgid "[Grayskull blogpost](https://conda-forge.org/blog/2020/03/05/grayskull/)" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:478 +msgid "[Pipx documentation](https://pipx.pypa.io/stable/)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:1 +msgid "Publish your Python package to PyPI" +msgstr "" + +#: ../../tutorials/publish-pypi.md:4 +msgid "Make sure they add /dist to their .gitignore file. We have not discussed GitHub workflows anywhere yet. Where does that fit?" +msgstr "" + +#: ../../tutorials/publish-pypi.md:8 +msgid "In the previous Python packaging lessons, you've learned:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:10 +msgid "What a Python package is" +msgstr "" + +#: ../../tutorials/publish-pypi.md:11 +msgid "How to make your code installable." +msgstr "" + +#: ../../tutorials/publish-pypi.md:19 +msgid "Build your package's source (sdist) and wheel distributions" +msgstr "" + +#: ../../tutorials/publish-pypi.md:20 +msgid "Setup an account on TestPyPI (the process is similar for PyPI)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:21 +msgid "Publish your package to TestPyPI and PyPI" +msgstr "" + +#: ../../tutorials/publish-pypi.md:23 +msgid "You will do all of your development work in this lesson using [Hatch](https://hatch.pypa.io/latest/)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:25 +msgid "Once your package is on PyPI you can publish it to conda-forge (which is a channel on conda) using [Grayskull](https://conda.github.io/grayskull/)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:28 +msgid "You will learn how to publish to conda-forge in the [next lesson](publish-conda-forge)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:32 +msgid "Graphic showing the high level packaging workflow. On the left you see a graphic with code, metadata and tests in it. Those items all go into your package. An arrow to the right takes you to a build distribution files box. Another arrow to the right takes you to a publish to PyPI box which has an arrow containing sdist and wheel that notes those files go to PyPI for hosting. From PyPI is an arrow containing sdist since you can then connect to conda-forge for an automated build that sends distributions from PyPI to conda-forge." +msgstr "" + +#: ../../tutorials/publish-pypi.md:34 +msgid "You need to build your Python package in order to publish it to PyPI (or Conda). The build process organizes your code and metadata into a distribution format that can be uploaded to PyPI and subsequently downloaded and installed by users." +msgstr "" + +#: ../../tutorials/publish-pypi.md:37 +msgid "TestPyPI vs PyPI" +msgstr "" + +#: ../../tutorials/publish-pypi.md:39 +msgid "There are two repositories associated with PyPI to which you can upload your Python package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:42 +msgid "**[TestPyPI](https://test.pypi.org):** TestPyPI is a package repository provided by PyPI that you can use for testing that your package can be uploaded, downloaded, and installed correctly. This is a great place to practice and learn how to publish a package without exposing your incomplete package on the real PyPI service." +msgstr "" + +#: ../../tutorials/publish-pypi.md:43 +msgid "**[PyPI](https://pypi.org):** This is the live, production PyPI repository where you can officially publish your Python package, and from which users will get your package. IMPORTANT: Only publish your package to PyPI when you are ready for it to be used by others and/or confident that it will become a package that you will maintain. PyPI is not a place to practice learning how to publish a Python package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:45 +msgid "The steps for publishing on TestPyPI vs. PyPI are similar with the exception of a different url. We will point out where they differ." +msgstr "" + +#: ../../tutorials/publish-pypi.md:48 +msgid "4 Steps for publishing a Python package on TestPyPI (or PyPI)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:50 +msgid "In this lesson you will learn how to publish your package to TestPyPI using [Hatch](https://hatch.pypa.io/latest/). There are 4 things that you need to do to publish your Python package: to TestPyPI. You need to:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:55 +msgid "**Create a package development environment**" +msgstr "" + +#: ../../tutorials/publish-pypi.md:56 +msgid "[**Build your package using `hatch build`**](../package-structure-code/python-package-distribution-files-sdist-wheel). Building a package is the process of turning your code into two types of distribution files: sdist and wheel. The wheel distribution file is particularly important for users who will `pip install` your package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:57 +msgid "**Create an account on TestPyPI (or PyPI)**: You will need to create a TestPyPI account and associated token which provides permissions for you to upload your package. When you later publish your package to PyPI, you will need a separate PyPI account and token." +msgstr "" + +#: ../../tutorials/publish-pypi.md:58 +msgid "**Publish to TestPyPI using `hatch publish`**" +msgstr "" + +#: ../../tutorials/publish-pypi.md:60 +msgid "In a future lesson, you will learn how to create an automated GitHub Actions workflow that publishes an updated version of your package to PyPI every time you create a GitHub release." +msgstr "" + +#: ../../tutorials/publish-pypi.md:64 +msgid "Learn more about building Python packages in our guide" +msgstr "" + +#: ../../tutorials/publish-pypi.md:68 +msgid "[Learn more about what building a Python package is](../package-structure-code/python-package-distribution-files-sdist-wheel)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:69 +msgid "[Learn more about the package distribution file that PyPI needs called the wheel](#python-wheel)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:70 +msgid "[Learn more about the package distribution file that conda-forge will need on PyPI called the sdist (source distribution)](#python-source-distribution)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:73 +msgid "Step 1: Create a Python package development environment" +msgstr "" + +#: ../../tutorials/publish-pypi.md:75 +msgid "The first step in building your package is to create a development environment. The Python environment will contain all of the dependencies needed to both install and work on your package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:77 +msgid "Use Hatch to create your environment." +msgstr "" + +#: ../../tutorials/publish-pypi.md:85 +msgid "Then view all of the current environments that hatch has access to:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:97 +msgid "Then activate the environment. Note that when you call a shell from a Hatch environment, it will automatically install your package into the environment in development or editable mode." +msgstr "" + +#: ../../tutorials/publish-pypi.md:107 +msgid "View what's in the environment using `pip list`:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:123 +msgid "At any time you can exit the environment using `exit`." +msgstr "" + +#: ../../tutorials/publish-pypi.md:137 +msgid "Hatch and environments" +msgstr "" + +#: ../../tutorials/publish-pypi.md:139 +msgid "Behind the scenes when hatch creates a new virtual environment, by default it uses venv[^venv] which is the default environment management tool that comes with Python installations." +msgstr "" + +#: ../../tutorials/publish-pypi.md:142 +msgid "Hatch will:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:144 +msgid "Create a new virtualenv (venv) that is located on your computer." +msgstr "" + +#: ../../tutorials/publish-pypi.md:145 +msgid "Install your package into the environment in editable mode (similar to `python -m pip install -e`). This means it installs both your project and your project's dependencies as declared in your pyproject.toml file." +msgstr "" + +#: ../../tutorials/publish-pypi.md:147 +msgid "Step 2: Build your package's sdist and wheel distributions" +msgstr "" + +#: ../../tutorials/publish-pypi.md:149 +msgid "Once you have your development environment setup, you are ready to build your package using Hatch. Remember that building is the process of turning your Python package file structure into two distribution files:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:151 +msgid "The [wheel distribution](#python-wheel) is a pre-built version of your package. It useful for users as it can be directly installed using a tool such as `pip`. This file has the extension `.whl`." +msgstr "" + +#: ../../tutorials/publish-pypi.md:152 +msgid "The [source distribution](#python-source-distribution) contains the files that make up your package in an unbuilt format. This file will have the extension `.tar.gz`." +msgstr "" + +#: ../../tutorials/publish-pypi.md:154 +msgid "You will use Hatch as a **Front end** tool that builds your package's sdist and wheel using the [hatchling](https://hatch.pypa.io/latest/) build back-end. The hatchling build back-end is used because you declared it in your pyproject.toml file in the [previous lesson](installable-code)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:158 +msgid "To build your package run `hatch build`:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:169 +msgid "Learn more about building a Python package" +msgstr "" + +#: ../../tutorials/publish-pypi.md:171 +msgid "You can learn more about building in the [build page of our packaging guide](../package-structure-code/python-package-distribution-files-sdist-wheel)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:175 +msgid "The sdist is important if you wish to [publish your package to conda-forge](publish-conda-forge). You will learn about this in a later lesson." +msgstr "" + +#: ../../tutorials/publish-pypi.md:179 +msgid "➜ hatch build ────────────────────────────────────── sdist ────────────────────────────────────── dist/pyospackage-0.1.tar.gz ────────────────────────────────────── wheel ────────────────────────────────────── dist/pyospackage-0.1-py3-none-any.whl" +msgstr "" + +#: ../../tutorials/publish-pypi.md:186 +msgid " Congratulations - you've created your Python package distribution files " +msgstr "" + +#: ../../tutorials/publish-pypi.md:188 +msgid "You've now built your Python package and created your package distribution files. The next step is to setup your account on TestPyPI so you can publish your package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:191 +msgid "Step 3. Setup your TestPyPI account" +msgstr "" + +#: ../../tutorials/publish-pypi.md:193 +msgid "Next, you'll setup an account on TestPyPI. Remember that you are using TestPyPI here instead of the real PyPI as a way to safely learn how to publish a package without accidentally \"releasing\" your package before it's ready." +msgstr "" + +#: ../../tutorials/publish-pypi.md:197 +msgid "TestPyPI vs. PyPI" +msgstr "" + +#: ../../tutorials/publish-pypi.md:198 +msgid "If you have a package that you are confident belongs on PyPI, all of the steps below will also work for you. When you publish using Hatch, you will call `hatch publish` to publish directly to PyPI instead of `hatch publish -r test` which publishes to TestPyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:201 +msgid "[Open up a web browser and go to the TestPyPI website](https://test.pypi.org/)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:202 +msgid "[Create an account](https://test.pypi.org/account/register/) if you don't already have one. Be sure to store your password in a safe place!" +msgstr "" + +#: ../../tutorials/publish-pypi.md:203 +msgid "Once you have an account setup, login to it." +msgstr "" + +#: ../../tutorials/publish-pypi.md:204 +msgid "Search on [https://test.pypi.org/](https://test.pypi.org/) (and also on [https://pypi.org/](https://pypi.org/)) to ensure that the package name that you have selected doesn't already exist. If you are using our test pyosPackage, then we suggest that you add your name or GitHub username to the end of the package name to ensure it's unique." +msgstr "" + +#: ../../tutorials/publish-pypi.md:206 +msgid "Example: `pyosPackage_yourNameHere`." +msgstr "" + +#: ../../tutorials/publish-pypi.md:0 +msgid "Renaming your project before publishing" +msgstr "" + +#: ../../tutorials/publish-pypi.md:211 +msgid "Required" +msgstr "" + +#: ../../tutorials/publish-pypi.md:213 +msgid "Search your publishing location(s) to make sure your new name isn't taken ([TestPyPI](https://test.pypi.org/), [PyPI](https://pypi.org/), [conda-forge](https://conda-forge.org/packages/))" +msgstr "" + +#: ../../tutorials/publish-pypi.md:214 +msgid "Update the project name in your pyproject.toml file (e.g. `name = \"pyospackage_yourNameHere\"`)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:215 +msgid "Update the module folder name to be the same (e.g. `src/pyospackage_yourNameHere`)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:216 +msgid "Rebuild your project (`hatch build`)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:217 +msgid "Publish your package to capture the name (continue this tutorial!)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:219 +msgid "Recommended" +msgstr "" + +#: ../../tutorials/publish-pypi.md:221 +msgid "Update the GitHub repository name to align with the new package name" +msgstr "" + +#: ../../tutorials/publish-pypi.md:222 +msgid "Update your local project folder to match the new package name (e.g. `pyospackage_yourNameHere/src`)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:223 +msgid "Update mentions of your repository name in other files (e.g. `README.md`)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:227 +msgid "This is a screenshot of the TestPyPI website. At the top in the search bar, you can see the search for pyosPackage. The search return says there were no results for pyosPackage Did you mean probpackage" +msgstr "" + +#: ../../tutorials/publish-pypi.md:229 +msgid "Before you try to upload to TestPyPI, check to see if the name of your package is already taken. You can do that using the search box at the top of the TestPyPI website." +msgstr "" + +#: ../../tutorials/publish-pypi.md:233 +msgid "Setup 2-factor (2FA) authentication" +msgstr "" + +#: ../../tutorials/publish-pypi.md:235 +msgid "2-factor authentication is a secure login process that allows you to use a backup device that only you can access to validate that the person logging in is really you. It addresses the issue of password phishing where someone else gains access to a password and can login to your account." +msgstr "" + +#: ../../tutorials/publish-pypi.md:238 +msgid "This matters on PyPI because someone could login to your account and upload a version of your package that has security issues. These issues will then impact all of your users when they download and install that version of the package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:240 +msgid "2-factor authentication is required for PyPI authentication as of 1 January 2024." +msgstr "" + +#: ../../tutorials/publish-pypi.md:244 +msgid "Step 4. Create a package upload token" +msgstr "" + +#: ../../tutorials/publish-pypi.md:246 +msgid "To upload your package to TestPyPI (or PyPI), you will need to create a token for your account first, and should then create a package-specific token. (If you completed this step previously, you can reuse the tokens when you upload your package again.)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:248 +msgid "Why create package-specific tokens?" +msgstr "" + +#: ../../tutorials/publish-pypi.md:250 +msgid "It's ideal to create a package-specific token. When you create an account-wide token this allows anyone with access to the account to then access all of your TestPyPI (or PyPI) projects. By creating a package-specific token, you are limiting the scope of the token to only your specific package. This is just a safe way to set things up for you particularly if you are collaborating with others on package development." +msgstr "" + +#: ../../tutorials/publish-pypi.md:253 +msgid "Follow the steps below to create your token." +msgstr "" + +#: ../../tutorials/publish-pypi.md:255 +msgid "Login to TestPyPI and go to your account settings" +msgstr "" + +#: ../../tutorials/publish-pypi.md:256 +msgid "Scroll down to the **API tokens** section" +msgstr "" + +#: ../../tutorials/publish-pypi.md:257 +msgid "Click on the **Add API Token** button" +msgstr "" + +#: ../../tutorials/publish-pypi.md:258 +msgid "If you are new to using TestPyPI and don't have any packages there yet, OR if you have other packages on TestPyPI but are uploading a new package, you will need to create an account-wide token." +msgstr "" + +#: ../../tutorials/publish-pypi.md:259 +msgid "When you create your token, be sure to copy the token value and store it in a secure place before closing that browser." +msgstr "" + +#: ../../tutorials/publish-pypi.md:261 +msgid "Your token should look something like this:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:263 +msgid "`pypi-abunchofrandomcharactershere...`" +msgstr "" + +#: ../../tutorials/publish-pypi.md:265 +msgid "It should start with `pypi` followed by a dash and a bunch of characters." +msgstr "" + +#: ../../tutorials/publish-pypi.md:267 +msgid "Upload to TestPyPI using Hatch" +msgstr "" + +#: ../../tutorials/publish-pypi.md:269 +msgid "Once you have your token, you are ready to publish to TestPyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:272 +msgid "Run `hatch publish -r test`" +msgstr "" + +#: ../../tutorials/publish-pypi.md:274 +msgid "`-r` stands for repository. In this case because you are publishing to TestPyPI you will use `-r test`. Hatch will then ask for a username and credentials." +msgstr "" + +#: ../../tutorials/publish-pypi.md:276 +msgid "Add the word `__token__` for your username. This tells TestPyPI that you are using a token value rather than a username." +msgstr "" + +#: ../../tutorials/publish-pypi.md:277 +msgid "Paste your TestPyPI token value in at the `Enter your credentials` prompt:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:288 +msgid "If your credentials are valid, and you have already run `hatch build` and thus have your 2 distribution files in a `dist/` directory then Hatch will publish your package to TestPyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:292 +msgid "Hatch also has a caching system so once you enter your credentials it will remember them." +msgstr "" + +#: ../../tutorials/publish-pypi.md:295 +msgid "Install your package from TestPyPI" +msgstr "" + +#: ../../tutorials/publish-pypi.md:297 +msgid "Once your package upload is complete, you can install it from TestPyPI. You can find the installation instructions on the TestPyPI landing page for your newly uploaded package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:302 +msgid "A screenshot of the TestPyPI page for pyosPackage. It says pyosPackage 0.1.0 at the top with the pip install instructions below. The landing page of the package has information from the package's README file." +msgstr "" + +#: ../../tutorials/publish-pypi.md:304 +msgid "This is an example landing page for the pyosPackage that was just uploaded. Notice at the top of the page there are instructions for how to install the package from TestPyPI. You can simply copy that code and use it to install your package from TestPyPI locally." +msgstr "" + +#: ../../tutorials/publish-pypi.md:307 +msgid "As an example, [check out our pyOpenSci pyosPackage landing page on TestPyPI](https://test.pypi.org/project/pyosPackage/). Notice that the page has information about the current package version and also installation instructions as follows:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:311 +msgid "`python -m pip install -i https://test.pypi.org/simple/ pyosPackage`" +msgstr "" + +#: ../../tutorials/publish-pypi.md:314 +msgid "Publishing to TestPyPI vs PyPI While you can install from TestPyPI it's not recommended that you publish to TestPyPI as a permanent way to install your package. In fact, you cannot, because TestPyPI may delete accounts after a time. TestPyPI is a perfect place to learn how to publish your package and test the installation process. But your end goal should be to publish to PyPI once you have figured out your workflow and your package is ready to deploy." +msgstr "" + +#: ../../tutorials/publish-pypi.md:318 +msgid "Time to install your package" +msgstr "" + +#: ../../tutorials/publish-pypi.md:320 +msgid "On your computer, activate the development environment that you wish to install your newly published package in." +msgstr "" + +#: ../../tutorials/publish-pypi.md:322 +msgid "Run the installation instructions for your package from TestPyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:0 +msgid "Conda" +msgstr "" + +#: ../../tutorials/publish-pypi.md:0 +msgid "venv Mac / Linux" +msgstr "" + +#: ../../tutorials/publish-pypi.md:346 +msgid "The value of end-to-end tools like hatch, flit and poetry" +msgstr "" + +#: ../../tutorials/publish-pypi.md:347 +msgid "In this lesson you are using Hatch and hatchling to create, build and publish your Python package. [Click here to learn about other packaging tools in the ecosystem.](../package-structure-code/python-package-build-tools.md)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:351 +msgid "teach them to setup trusted publisher for actions... in the actions lesson https://pypi.org/help/#twofa" +msgstr "" + +#: ../../tutorials/publish-pypi.md:354 +msgid "from PyPI: https://pypi.org/help/#apitoken - You can create a token for an entire PyPI account, in which case, the token will work for all projects associated with that account. Alternatively, you can limit a token's scope to a specific project." +msgstr "" + +#: ../../tutorials/publish-pypi.md:357 +msgid "Package-specific token vs trusted publisher" +msgstr "" + +#: ../../tutorials/publish-pypi.md:359 +msgid "For long run maintenance of your package, you have two options related to PyPI publication." +msgstr "" + +#: ../../tutorials/publish-pypi.md:362 +msgid "You can create a package-specific token which you will use to publish your package (manually) to PyPI. This is a great option if you don't wish to automate your PyPI publication workflow." +msgstr "" + +#: ../../tutorials/publish-pypi.md:363 +msgid "You can also create an automated publication workflow on GitHub using GitHub Actions. This is a great way to make the publication process easier and it also supports a growing maintainer team. In this case we suggest you don't worry about the token and instead setup a specific GitHub Actions that publishes your package when you make a release. You can then create a \"trusted publisher\" workflow on PyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:365 +msgid "You will learn how to create the automated trusted publisher workflow in a followup lesson." +msgstr "" + +#: ../../tutorials/publish-pypi.md:368 +msgid "OPTIONAL: If you want to use a manual token-based publication workflow" +msgstr "" + +#: ../../tutorials/publish-pypi.md:370 +msgid "If you plan to use your token regularly to publish to PyPI, we strongly recommend going through the above steps again to create a token specific to your new package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:373 +msgid "To do this:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:374 +msgid "Go to TestPyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:375 +msgid "Navigate to the \"Your Projects\" section of your account" +msgstr "" + +#: ../../tutorials/publish-pypi.md:376 +msgid "Click on the manage button for the project that you wish to add a token for" +msgstr "" + +#: ../../tutorials/publish-pypi.md:377 +msgid "Go to settings" +msgstr "" + +#: ../../tutorials/publish-pypi.md:378 +msgid "Click on \"Create a token for your-package-name-here\"" +msgstr "" + +#: ../../tutorials/publish-pypi.md:379 +msgid "Create the token and follow the steps above publish your package using the repository specific token." +msgstr "" + +#: ../../tutorials/publish-pypi.md:381 +msgid "And you're all done!" +msgstr "" + +#: ../../tutorials/publish-pypi.md:383 +msgid "You have published your package to TestPyPI!" +msgstr "" + +#: ../../tutorials/publish-pypi.md:385 +msgid "Congratulations. You have now successfully published your package to TestPyPI. If you have a package that is ready for real-world use on the real PyPI, then you can follow the same steps (with the differences noted above) to publish it on PyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:387 +msgid "Once you publish on PyPI, you can then easily add your package to the conda-forge ecosystem using the [grayskull](https://conda-forge.org/blog/posts/2020-03-05-grayskull/) tool." +msgstr "" + +#: ../../tutorials/publish-pypi.md:389 +msgid "You will learn how to do that in the next lesson." +msgstr "" + +#: ../../tutorials/publish-pypi.md:396 +msgid "https://docs.python.org/3/library/venv.html" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:1 +msgid "Make your Python package PyPI ready - pyproject.toml" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:3 +msgid "In [the installable code lesson](installable-code), you learned how to add the bare minimum information to a `pyproject.toml` file to make it installable. You then learned how to [publish a bare minimum version of your package to PyPI](publish-pypi.md)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:5 +msgid "Following that you learned how to add a:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:6 +msgid "[README.md](add-readme)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:7 +msgid "[LICENSE](add-license-coc) and" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:8 +msgid "[CODE_OF_CONDUCT](add-coc)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:10 +msgid "to the root of your project directory." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:12 +msgid "To enhance the visibility of your package on PyPI and provide more information about its compatibility with Python versions, project development status, and project maintainers, you should add additional metadata to your `pyproject.toml` file. This lesson will guide you through the process." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:24 +msgid "More about the `pyproject.toml` file and how it's used to store different types of metadata about your package" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:25 +msgid "How to declare information (metadata) about your project to help users find and understand it on PyPI." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:27 +msgid "If you wish to learn more about the `pyproject.toml` format, [check out this page. ](../package-structure-code/pyproject-toml-python-package-metadata.md)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:0 +msgid "Click for lesson takeaways" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:34 +msgid "When creating your pyproject.toml file, consider the following:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:36 +msgid "There are only two required metadata tables that you need to install and publish your Python package:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:37 +msgid "**[build-system]**" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:38 +msgid "**[project]**." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:39 +msgid "The **[project]** table stores your package's metadata. Within the **[project]** table, There are only two _required_ fields:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:40 +msgid "**name=**" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:41 +msgid "**version=**" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:42 +msgid "You should add more metadata to the `[project]` table as it will make it easier for users to find your project on PyPI. And it will also make it easier for installers to understand how to install your package." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:43 +msgid "When you are adding classifiers to the **[project]** table, only use valid values from [PyPI's classifier page](https://PyPI.org/classifiers/). An invalid value here will raise an error when you build and publish your package on PyPI." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:44 +msgid "There is no specific order for tables in the `pyproject.toml` file. However, fields need to be placed within the correct tables. For example `requires =` always need to be in the **[build-system]** table." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:45 +msgid "We suggest that you include your **[build-system]** table at the top of your `pyproject.toml` file." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:50 +msgid "The `pyproject.toml` file is a human and machine-readable file that serves as the primary configuration file for your Python package." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:54 +msgid "[Building your package](build-package) is the step that created the distribution files that are required for you to publish to PyPI." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:58 +msgid "About the .toml format" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:60 +msgid "The **pyproject.toml** file is written in [TOML (Tom's Obvious, Minimal Language) format](https://toml.io/en/). TOML is an easy-to-read structure that is based on key/value pairs. Each section in the **pyproject.toml** file contains a `[table identifier]`. The TOML format can be compared to other structured formats such as`.json`. However, the TOML format was designed to be easier to read for humans." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:62 +msgid "Below you can see the `[build-system]` table. Within that table there are two required key/value pairs." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:65 +msgid "`requires =` is the key and the value is `[\"hatchling\"]` within the `[build-system]` array specified by square brackets `[]`." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:75 +msgid "What is the pyproject.toml used for?" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:77 +msgid "The pyproject.toml file tells your build tool:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:79 +msgid "What build backend to use to build your package (we are using `hatchling` in this tutorial but there are [many others to choose from](/package-structure-code/python-package-build-tools))." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:80 +msgid "How and where to retrieve your package's version:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:81 +msgid "**statically** where you declare the version `version = \"0.1.0\"` or" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:82 +msgid "**dynamically** where the tool looks to the most recent tag in your history to determine the current version." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:83 +msgid "What dependencies your package needs" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:84 +msgid "What versions of Python your package supports (important for your users)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:86 +msgid "The `pyproject.toml` file also makes it easy for anyone browsing your GitHub repository to quickly understand your package's structure such as:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:89 +msgid "How your package is built," +msgstr "" + +#: ../../tutorials/pyproject-toml.md:90 +msgid "What Python versions and operating systems it supports" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:91 +msgid "What it does," +msgstr "" + +#: ../../tutorials/pyproject-toml.md:92 +msgid "Who maintains it" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:94 +msgid "Finally, the pyproject.toml file is also often used to configure tools such as static type checkers (e.g. mypy) and code formatters/linters (e.g. black, ruff)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:97 +msgid "Check out the [PyPA documentation](https://packaging.python.org/en/latest/tutorials/packaging-projects/#choosing-a-build-backend) if you are interested in setting build configurations for other tools." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:99 +msgid "Note that some build tools may deviate in how they store project metadata. As such you may want to refer to their documentation if you decide to use a tool other than Hatch and hatchling. We have selected hatchling and hatch as our tool of choice for this tutorial as it adheres to PyPA rules and guidelines." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:103 +msgid "How is pyproject.toml metadata used?" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:105 +msgid "The pyproject.toml file is the file that your build tool uses to populate a `METADATA` that is included in your Python distribution files that get published to PyPI. This `METADATA` file is then used by PyPI to populate your package's PyPI landing page and help users filter through the tens of thousands of packages published there." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:108 +msgid "Image showing the left side bar of PyPI for the package xclim. The section at the top says Classifier. Below there is a list of items including Development status, intended audience, License, natural language, operating system, programming language and topic. Below each of those sections are various classifier options.\" width=\"300px\">" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:113 +msgid "When you add the classifier section to your pyproject.toml and your package is built, the build tool organizes the metadata into a format that PyPI can understand and represent on your PyPI landing page. These classifiers also allow users to sort through packages by version of python they support, categories and more." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:119 +msgid "A more in-depth overview of pyproject.toml files" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:121 +msgid "[Our guidebook page has a more in depth overview of this file](../package-structure-code/pyproject-toml-python-package-metadata/)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:124 +msgid "How to update your pyproject.toml file" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:126 +msgid "In the last lesson, you created a bare-bones pyproject.toml file that contained the core elements needed to build your package:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:130 +msgid "A `[build-system]` table where you defined your project's backend build tool (`hatchling`)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:131 +msgid "A `[project]` table where you defined your project's version and name." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:133 +msgid "The `pyproject.toml` file that you created, looked like this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:145 +msgid "Your next step is to add additional recommended metadata fields that will both help users find your package on PyPI and also better describe the scope of your package. Once you add this metadata, you don't have to do it again. These metadata fields will only be updated periodically when you do something such as:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:148 +msgid "drop a package dependency" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:149 +msgid "modify what Python versions your package supports." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:151 +msgid "More on hatchling" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:154 +msgid "The documentation for the hatchling back-end is [here](https://hatch.pypa.io/latest/config/metadata/)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:157 +msgid "Step 1: Add Author, maintainer and project description" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:159 +msgid "After completing the [installable code tutorial](installable-code), you should have a pyproject.toml file with a project name and a version in the `[project]` table." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:167 +msgid "Add the following to your table:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:169 +msgid "A **description** of your package. This should be a single line and should briefly describe the goal of your package using non technical terms if as all possible!" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:170 +msgid "package **authors**" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:171 +msgid "package **maintainers**" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:173 +msgid "The `description` is just a string like the other values you've set:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:184 +msgid "When you add authors and maintainers you need to use a format that will look like a Python list with a dictionary within it:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:198 +msgid "Author names & emails" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:202 +msgid "There is a quirk with PyPI for authors that have names but not emails in the pyproject.toml. If you are missing the email for one or more authors or maintainers, like this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:211 +msgid "Then we suggest that you only provide names in your list of names to ensure that everything renders properly on your PyPI page - like this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:220 +msgid "don't have emails for everyone, we suggest that you only add names." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:223 +msgid "Your `pyproject.toml` file now should look like the example below. It is OK if you only have 1 author and the same author is also maintainer of your package:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:0 +msgid "Learn More: What's the difference between author and maintainer in open source?" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:251 +msgid "When adding maintainers and authors, you may want to think about the difference between the two." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:253 +msgid "Authors generally include people who:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:254 +msgid "originally created / designed developed the package and" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:255 +msgid "people who add new functionality to the package." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:257 +msgid "Whereas maintainers are the people that are currently, actively working on the project. It is often the case that there is overlap in authors and maintainers. As such these lists may be similar or the same." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:259 +msgid "A good example of when the lists might diverge is sometimes you have a package where an initial author developed it and then stepped down as a maintainer to move on to other things. This person may continue to be considered an author but no longer actively maintains the package." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:261 +msgid "It is important to note that there are many ways to define author vs maintainer and we don't prescribe a single approach in this tutorial." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:263 +msgid "However, we encourage you to consider carefully, for PyPI publication, who you want to have listed as authors and maintainers on your PyPI landing page." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:267 +msgid "Step 2: Add README and license" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:269 +msgid "In the previous lessons, you added both a [README.md](add-readme) file and a [LICENSE](add-license-coc) to your package repository. Once you have those files, you can add them to your pyproject.toml file as links following the example below." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:297 +msgid "Step 3: Specify Python version with `requires-python`" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:299 +msgid "Add the `requires-python` field to your `pyproject.toml` `[project]` table. The `requires-python` field helps pip identify which Python versions that your package supports. It is set to a single value. The [packaging specification](https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata-requires-python) defines`requires-python` as a string that uses version specifiers. Most projects will specify the oldest Python version supported by the package. In some advanced cases, an upper bound is set to indicate which future Python versions, if any, will be supported." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:331 +msgid "Step 4: Specify Dependencies" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:333 +msgid "Next add your dependencies table to the project table. The `dependencies =` section contains a list (or array in the toml language) of the Python packages that your package requires to run properly in a Python environment. Similar to the requirements listed in the `[build-system]` table above:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:341 +msgid "dependencies are added in an array (similar to a Python list) structure." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:347 +msgid "A dependency can be limited to specific versions using a **version specifier.** If the dependency has no version specifier after the dependency name, your package can use any version of the dependent package. Code changes over time, bugs are fixed, APIs change, and so it's good to be clear about which version of the dependency you wrote your code to be compatible with - a package you wrote this year probably isn't compatible with numpy v0.0.1!" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:351 +msgid "[Learn more about various ways to specify ranges of package versions here.](https://packaging.python.org/en/latest/specifications/version-specifiers/#id5)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:353 +msgid "The most common version specifier is a **lower bound,** allowing any version higher than the specified version. Ideally you should set this to the lowest version that is still compatible with your package, but in practice for new packages this is often set at the version that was current at the time the package was written[^lowerbound]." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:358 +msgid "Lower bounds look like this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:364 +msgid "Commas are used to separate individual dependencies, and each package in your `dependencies` section can use different types of version specifiers:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:375 +msgid "Your `pyproject.toml` file will now look like this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:405 +msgid "Pin dependencies with caution" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:406 +msgid "\"Pinning\" a dependency means setting it to a specific version, like this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:408 +msgid "`numpy == 1.0`." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:410 +msgid "If you are building a library package that other developers will depend upon, you must be cautious before pinning to a precise dependency version. Applications, such as production websites, will often pin their dependencies since other packages will not depend on their project. This is because users will be installing your package into various environments. A dependency pinned to a single specific version can make resolving a Python environment more challenging. As such only pin dependencies to a specific version if you absolutely need to do so." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:418 +msgid "Similarly, you should be cautious when specifying an upper bound on a package. These two specifications are equivalent:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:426 +msgid "One build tool that you should be aware of that pins dependencies to an upper bound by default is Poetry. [Read more about how to safely add dependencies with Poetry, here.](challenges-with-poetry)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:429 +msgid "Step 5: Add PyPI classifiers" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:431 +msgid "Next you will add classifiers to your `pyproject.toml` file. The value for each classifier that you add to your `pyproject.toml` file must come from the list of [PyPI accepted classifier values found here](https://PyPI.org/classifiers/). Any deviations in spelling and format will cause issues when you publish to PyPI." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:433 +msgid "What happens when you use incorrect classifiers?" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:436 +msgid "If you do not [use standard classifier values](https://PyPI.org/classifiers/), when you try to publish your package on PyPI it will be rejected. 😔 Don't worry if PyPI rejects you on your first try! It has happened to all of us." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:439 +msgid "Review that list and add items below to your `pyproject.toml` file:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:441 +msgid "development status" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:442 +msgid "intended audiences" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:443 +msgid "topic" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:444 +msgid "license and" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:445 +msgid "programming language support" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:447 +msgid "The classifier key should look something like the example below. A few notes:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:449 +msgid "Your classifier values might be different depending upon the license you have selected for your package, your intended audience, development status of your package and the Python versions that you support" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:450 +msgid "You can add as many classifiers as you wish as long as you use the [designated PyPI classifier values](https://PyPI.org/classifiers/)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:490 +msgid "Note that while classifiers are not required in your `pyproject.toml` file, they will help users find your package. As such we strongly recommend that you add them." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:492 +msgid "Step 6: Add the `[project.urls]` table" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:494 +msgid "Finally, add the project.urls table to your pyproject.toml file." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:496 +msgid "`project.urls` contains links that are relevant for your project. You might want to include:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:498 +msgid "**Homepage:** A link to your published documentation for your project. If you are working through this tutorial, then you may not have this link yet. That's ok, you can skip it for the time being." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:499 +msgid "**Bug reports:** a link to your issues / discussions or wherever you want users to report bugs." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:500 +msgid "**Source:** the GitHub / GitLab link for your project." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:546 +msgid "There are many other urls that you can add here. Check out the [README file here for an overview](https://github.com/patrick91/links-demo)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:549 +msgid "Putting it all together - your completed pyproject.toml file" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:551 +msgid "Below is an example of a complete `pyproject.toml` file that is commented with all of the sections we discussed above." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:0 +msgid "Appendix - Click for a fully commented pyproject.toml file" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:601 +msgid "Below is a fully commented pyproject.toml file if you want to use it for reference." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:666 +msgid "Example `pyproject.toml` files" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:668 +msgid "Below are some examples of `pyproject.toml` files from various packages in the scientific and pyOpenSci ecosystem." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:669 +msgid "[PyPA's fully documented example pyproject.toml file](https://github.com/pypa/sampleproject/blob/main/pyproject.toml)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:670 +msgid "[taxpasta has a nicely organized pyproject.toml file and is a pyOpenSci approved package](https://github.com/taxprofiler/taxpasta/blob/f9f6eea2ae7dd08bb60a53dd49ad77e4cf143573/pyproject.toml)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:676 +msgid "At this point you've created:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:678 +msgid "A [README.md](add-readme) file for your package" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:679 +msgid "A [CODE_OF_CONDUCT.md](add-coc) file to support your user community" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:680 +msgid "And a [LICENSE](add-license-coc) file which provides legal boundaries around how people can and can't use your software" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:682 +msgid "You also learned [how to publish your package to (test)PyPI](publish-pypi)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:684 +msgid "Publish a new version of your package to PyPI" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:686 +msgid "You are now ready to publish a new version of your Python package to (test) PyPI. When you do this you will see that the landing page for your package now contains a lot more information." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:688 +msgid "Try to republish now." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:690 +msgid "First, update the version of your package in your pyproject toml file. Below version is updated from `0.1` to `0.1.1`." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:703 +msgid "Now use hatch to publish the new version of your package to test.PyPI.org." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:710 +msgid "Next (optional) step - publishing to conda-forge" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:712 +msgid "You now have all of the skills that you need to publish your package to PyPI." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:715 +msgid "If you also want to publish your package on conda-forge (which is a channel within the conda ecosystem), you will learn how to do that in the next lesson." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:719 +msgid "Really good resources from jeremiah https://daniel.feldroy.com/posts/2023-08-pypi-project-urls-cheatsheet useful (and the linked links-demo even more so)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:356 +msgid "Some packaging tools will do this for you when you add a dependency using their cli interface. For example [`poetry add`](https://python-poetry.org/docs/cli/#add) will add the most recent version with a `^` specifier, and [`pdm add`](https://pdm-project.org/latest/reference/cli/#add) will add the most recent version with `>=`." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:1 +msgid "Using Hatch to Migrate setup.py to a pyproject.toml" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:3 +msgid "Hatch can be particularly useful to generate your project's `pyproject.toml` if your project already has a `setup.py`." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:5 +msgid "Note" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:8 +msgid "This step is not necessary and is only useful if your project already has a `setup.py` file defined." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:9 +msgid "If your project does not already define a `setup.py` see [Make your Python code installable](installable-code.md)" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:17 +msgid "The process of using Hatch to transition to using `pyproject.toml` for projects that already have a `setup.py` defined." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:20 +msgid "What is Hatch?" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:22 +msgid "Hatch is a Python package manager designed to streamline the process of creating, managing, and distributing Python packages. It provides a convenient CLI (Command-Line Interface) for tasks such as creating new projects, managing dependencies, building distributions, and publishing packages to repositories like PyPI." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:28 +msgid "See [Get to know Hatch](get-to-know-hatch.md) for more information." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:31 +msgid "Prerequisites" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:33 +msgid "Before we begin, ensure that you have Hatch installed on your system. You can install it via pip:" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:39 +msgid "Sample Directory Tree" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:41 +msgid "Let's take a look at a sample directory tree structure before and after using `hatch init`:" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:43 +msgid "Before `hatch init`" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:59 +msgid "After `hatch init`" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:77 +msgid "As you can see, the main change after running `hatch init` is the addition of the `pyproject.toml` file in the project directory." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:79 +msgid "Step-by-Step Guide" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:81 +msgid "Now, let's walk through the steps to use Hatch to create a `pyproject.toml` file for your project." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:83 +msgid "**Navigate to Your Project Directory**: Open your terminal or command prompt and navigate to the directory where your Python project is located." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:85 +msgid "**Initialize Hatch**: Run the following command to initialize Hatch in your project directory:" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:91 +msgid "**Review and Customize**: After running the previous command, Hatch will automatically generate a `pyproject.toml` file based on your existing project configuration. Take some time to review the contents of the generated `pyproject.toml` file. You may want to customize certain settings or dependencies based on your project's requirements (see [pyproject.toml tutorial](pyproject-toml.md) for more information about the `pyproject.toml`)." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:93 +msgid "**Verify**: Verify that the `pyproject.toml` file accurately reflects your project configuration and dependencies. You can manually edit the file if needed, but be cautious and ensure that the syntax is correct." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:95 +msgid "**Delete setup.py**: Since we're migrating to using `pyproject.toml` exclusively, the `setup.py` file becomes unnecessary. You can safely delete it from your project directory." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:97 +msgid "**Test Build**: Before proceeding further, it's essential to ensure that your project builds successfully using only the `pyproject.toml` file. Run the following command to build your project:" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:103 +msgid "This command will build your project based on the specifications in the `pyproject.toml` file. Make sure to check for any errors or warnings during the build process." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:105 +msgid "**Test Existing Functionality**: After successfully building your project with `pyproject.toml`, it's crucial to ensure that your project's existing functionality remains intact. Run any pre-existing tests to verify that everything still works as expected." +msgstr "" + diff --git a/locales/es/LC_MESSAGES/messages.po b/locales/es/LC_MESSAGES/messages.po new file mode 100644 index 00000000..c5eb651c --- /dev/null +++ b/locales/es/LC_MESSAGES/messages.po @@ -0,0 +1,3972 @@ +msgid "" +msgstr "" +"Project-Id-Version: pyos-python-package-guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-04-30 18:44-0600\n" +"PO-Revision-Date: 2025-05-01 18:41\n" +"Last-Translator: \n" +"Language-Team: Spanish\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=2; plural=(n != 1);\n" +"X-Crowdin-Project: pyos-python-package-guide\n" +"X-Crowdin-Project-ID: 785976\n" +"X-Crowdin-Language: es-ES\n" +"X-Crowdin-File: /translation2/locales/templates/LC_MESSAGES/tutorials.pot\n" +"X-Crowdin-File-ID: 50\n" +"Language: es_ES\n" + +#: ../../tutorials/add-license-coc.md:1 +msgid "Add a `LICENSE` & `CODE_OF_CONDUCT` to your Python package" +msgstr "" + +#: ../../tutorials/add-license-coc.md:3 +msgid "In the [previous lesson](add-readme) you:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:5 +msgid " Created a basic `README.md` file for your scientific Python package" +msgstr "" + +#: ../../tutorials/add-license-coc.md:7 +msgid " Learned about the core components that are useful to have in a `README` file." +msgstr "" + +#: ../../tutorials/add-license-coc.md:9 +#: ../../tutorials/add-readme.md:10 +msgid "Learning objectives" +msgstr "" + +#: ../../tutorials/add-license-coc.md:12 +#: ../../tutorials/add-readme.md:12 +#: ../../tutorials/installable-code.md:41 +#: ../../tutorials/pyproject-toml.md:22 +#: ../../tutorials/setup-py-to-pyproject-toml.md:15 +msgid "In this lesson you will learn:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:14 +msgid "How to select a license and add a `LICENSE` file to your package repository, with a focus on the GitHub interface." +msgstr "" + +#: ../../tutorials/add-license-coc.md:15 +msgid "How to add a `CODE_OF_CONDUCT` file to your package repository." +msgstr "" + +#: ../../tutorials/add-license-coc.md:16 +msgid "How you can use the Contributors Covenant website to add generic language as a starting place for your `CODE_OF_CONDUCT`." +msgstr "" + +#: ../../tutorials/add-license-coc.md:19 +msgid "What is a license?" +msgstr "" + +#: ../../tutorials/add-license-coc.md:21 +msgid "A license contains legal language about how users can use and reuse your software. To set the `LICENSE` for your project, you:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:23 +msgid "Create a `LICENSE` file in your project directory that specifies the license that you choose for your package." +msgstr "" + +#: ../../tutorials/add-license-coc.md:24 +msgid "Reference that file in your `pyproject.toml` data where metadata are set." +msgstr "" + +#: ../../tutorials/add-license-coc.md:26 +msgid "By adding the `LICENSE` file to your `pyproject.toml` file, the `LICENSE` will be included in your package's metadata which is used to populate your package's PyPI landing page. The `LICENSE` is also used in your GitHub repository's landing page interface." +msgstr "" + +#: ../../tutorials/add-license-coc.md:28 +msgid "What license should you use?" +msgstr "" + +#: ../../tutorials/add-license-coc.md:30 +msgid "We suggest that you use a permissive license that accommodates the other most commonly used licenses in the scientific Python ecosystem (MIT[^mit] and BSD-3[^bsd3]). If you are unsure, use MIT given it's the generally recommended license on [choosealicense.com](https://choosealicense.com/)." +msgstr "" + +#: ../../tutorials/add-license-coc.md:33 +msgid "Licenses for the scientific Python ecosystem" +msgstr "" + +#: ../../tutorials/add-license-coc.md:34 +msgid "[We discuss licenses for the scientific Python ecosystem in more detail here in our guidebook.](../documentation/repository-files/license-files)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:37 +msgid "Where should the `LICENSE` file live" +msgstr "" + +#: ../../tutorials/add-license-coc.md:39 +msgid "Your `LICENSE` file should be placed at the root of your package's repository. When you add the `LICENSE` at the root, GitHub will automagically discover it and provide users with a direct link to your `LICENSE` file within your GitHub repository." +msgstr "" + +#: ../../tutorials/add-license-coc.md:45 +msgid "Image showing the GitHub repository for SunPy an accepted pyOpenSci package." +msgstr "" + +#: ../../tutorials/add-license-coc.md:47 +msgid "Notice at the top of the README portion of the GitHub landing page, there are three tabs directly linking to the `README` file which is visible, the `CODE_OF_CONDUCT` file and one that specifies the license that SunPy uses. These files are discovered by GitHub because they are placed in the root of the project directory using standard naming conventions." +msgstr "" + +#: ../../tutorials/add-license-coc.md:54 +msgid "How to add a `LICENSE` file to your package directory" +msgstr "" + +#: ../../tutorials/add-license-coc.md:56 +msgid "There are several ways to add a `LICENSE` file:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:58 +msgid "When you create a new repository on GitHub, it will ask you if you wish to add a `LICENSE` file at that time. If you select yes, it will create the file for you." +msgstr "" + +#: ../../tutorials/add-license-coc.md:59 +msgid "You can add a `LICENSE` through the GitHub gui following the [ instructions here](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository)." +msgstr "" + +#: ../../tutorials/add-license-coc.md:60 +msgid "You can add the file manually as we are doing in this lesson." +msgstr "" + +#: ../../tutorials/add-license-coc.md:63 +msgid "If you completed the past lessons including" +msgstr "" + +#: ../../tutorials/add-license-coc.md:65 +msgid "[Making your code installable](installable-code.md) and" +msgstr "" + +#: ../../tutorials/add-license-coc.md:66 +msgid "[publishing your package to PyPI](publish-pypi.md)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:68 +msgid "then you already have a `LICENSE` file containing text for the MIT license in your Python package. Thus you can skip to the next section of this tutorial which walks you through adding a `CODE_OF_CONDUCT`." +msgstr "" + +#: ../../tutorials/add-license-coc.md:70 +msgid "If you don't yet have a `LICENSE` file in your directory, then continue reading." +msgstr "" + +#: ../../tutorials/add-license-coc.md:73 +msgid "How to add a `LICENSE` to your package - the manual way" +msgstr "" + +#: ../../tutorials/add-license-coc.md:75 +msgid "If you don't already have a `LICENSE` file, and you are not yet using a platform such as GitHub or GitLab, then you can create a `LICENSE` file by" +msgstr "" + +#: ../../tutorials/add-license-coc.md:77 +msgid "Create a new file called `LICENSE`. If you are using shell you can type:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:84 +msgid "Go to [choosealicense.com](https://choosealicense.com/)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:85 +msgid "Select permissive license" +msgstr "" + +#: ../../tutorials/add-license-coc.md:86 +msgid "It will suggest that you use the [MIT license](https://choosealicense.com/licenses/mit/)." +msgstr "" + +#: ../../tutorials/add-license-coc.md:87 +msgid "Copy the license text that it provides into your `LICENSE` file that you created above." +msgstr "" + +#: ../../tutorials/add-license-coc.md:88 +msgid "Save your file. You're all done!" +msgstr "" + +#: ../../tutorials/add-license-coc.md:90 +msgid "An overview of licenses in the scientific Python ecosystem" +msgstr "" + +#: ../../tutorials/add-license-coc.md:93 +msgid "In the pyOpenSci [packaging guidebook](../documentation/repository-files/license-files), we provide an overview of licenses in the scientific Python ecosystem. We review why license files are important, which ones are most commonly used for scientific software and how to select the correct license." +msgstr "" + +#: ../../tutorials/add-license-coc.md:95 +msgid "If you want a broad overview of why licenses are important for protecting open source software, [check out this blog post that overviews the legal side of things.](https://opensource.guide/legal/#just-give-me-the-tldr-on-what-i-need-to-protect-my-project)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:0 +msgid "Instructions for adding a `LICENSE` file within the GitHub interface" +msgstr "" + +#: ../../tutorials/add-license-coc.md:0 +msgid "Add license: new GitHub repository" +msgstr "" + +#: ../../tutorials/add-license-coc.md:106 +msgid "When you create a new GitHub repository you can add a `LICENSE` file through the GitHub interface." +msgstr "" + +#: ../../tutorials/add-license-coc.md:111 +msgid "Screenshot of the create new repository interface that GitHub provides. The elements of this are the owner and repository name for the new repo. Below that you can add a description of the repository. Below that you can set it to be public or private. At the bottom of the interface there is an Add a README checkbox where it will add a blank readme file for you. At the very bottom there is a line to add a .gitignore file and another to choose a license." +msgstr "" + +#: ../../tutorials/add-license-coc.md:113 +msgid "Image showing the GitHub interface that allows you to add a `LICENSE` and `README` file when you create a new repository." +msgstr "" + +#: ../../tutorials/add-license-coc.md:0 +msgid "Add `LICENSE`: Existing GitHub repository" +msgstr "" + +#: ../../tutorials/add-license-coc.md:119 +msgid "If you already have a GitHub repository for your package, then you can add a `LICENSE` using the GitHub interface by adding a new file to the repository." +msgstr "" + +#: ../../tutorials/add-license-coc.md:121 +msgid "Follow the instructions to select and add a license to your repository on the [GitHub LICENSE page](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository) ." +msgstr "" + +#: ../../tutorials/add-license-coc.md:122 +msgid "Once you have added your `LICENSE` file, be sure to sync your git local repository with the repository on GitHub.com. This means running `git pull` to update your local branch." +msgstr "" + +#: ../../tutorials/add-license-coc.md:125 +msgid "Image showing what the LICENSE file looks like in the GItHub interface. At the top you can see the actual license which in this image is BSD 3-clause New or revised license. Then there is some text describing both what the license is and the associated permissions for that specific license. At the bottom of the image, the actual text for the license is shown in the LICENSE file." +msgstr "" + +#: ../../tutorials/add-license-coc.md:127 +msgid "You can view a summary of the `LICENSE` chosen on your project's GitHub landing page." +msgstr "" + +#: ../../tutorials/add-license-coc.md:134 +msgid "Now you know how to add a `LICENSE` to your project. Next, you'll learn about the `CODE_OF_CONDUCT.md` file and how to add it to your package directory." +msgstr "" + +#: ../../tutorials/add-license-coc.md:139 +msgid "What is a code of conduct file?" +msgstr "" + +#: ../../tutorials/add-license-coc.md:141 +msgid "A `CODE_OF_CONDUCT` file is used to establish guidelines for how people in your community interact." +msgstr "" + +#: ../../tutorials/add-license-coc.md:143 +msgid "This file is critical to supporting your community as it grows. The `CODE_OF_CONDUCT`:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:146 +msgid "Establishes guidelines for how users and contributors interact with each other and you in your software repository." +msgstr "" + +#: ../../tutorials/add-license-coc.md:147 +msgid "Identifies negative behaviors that you don't want in your interactions." +msgstr "" + +#: ../../tutorials/add-license-coc.md:149 +msgid "You can use your code of conduct as a tool that can be referenced when moderating challenging conversations." +msgstr "" + +#: ../../tutorials/add-license-coc.md:151 +msgid "What to put in your `CODE_OF_CONDUCT` file" +msgstr "" + +#: ../../tutorials/add-license-coc.md:153 +msgid "If you are unsure of what language to add to your `CODE_OF_CONDUCT` file, we suggest that you adopt the [contributor covenant language](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) as a starting place." +msgstr "" + +#: ../../tutorials/add-license-coc.md:156 +msgid "![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:156 +msgid "Contributor Covenant" +msgstr "" + +#: ../../tutorials/add-license-coc.md:158 +msgid "The `CODE_OF_CONDUCT.md` should be placed at the root of your project directory, similar to the `LICENSE` file." +msgstr "" + +#: ../../tutorials/add-license-coc.md:160 +msgid "How to add a `CODE_OF_CONDUCT` file to your package directory" +msgstr "" + +#: ../../tutorials/add-license-coc.md:162 +msgid "Add a `CODE_OF_CONDUCT.md` file to the root of your repository if it doesn't already exist." +msgstr "" + +#: ../../tutorials/add-license-coc.md:168 +msgid "Visit the [contributor covenant website](https://www.contributor-covenant.org/) and add [the markdown version of their code of conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/code_of_conduct.md) to your `CODE_OF_CONDUCT.md` file. Be sure to fill in any placeholder information. Read the text closely to ensure you both understand it and also agree with its contents!" +msgstr "" + +#: ../../tutorials/add-license-coc.md:170 +msgid "That's it - you've now added a code of conduct to your package directory." +msgstr "" + +#: ../../tutorials/add-license-coc.md:172 +msgid "Additional Code of Conduct resources" +msgstr "" + +#: ../../tutorials/add-license-coc.md:175 +msgid "[ Guide: `CODE_OF_CONDUCT.md` files](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:176 +msgid "[pyOpenSci package guide `CODE_OF_CONDUCT.md` overview](https://www.pyopensci.org/python-package-guide/documentation/repository-files/code-of-conduct-file.html)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:179 +#: ../../tutorials/add-readme.md:233 +#: ../../tutorials/publish-conda-forge.md:463 +#: ../../tutorials/pyproject-toml.md:673 +msgid " Wrap up" +msgstr "" + +#: ../../tutorials/add-license-coc.md:181 +msgid "In this lesson and the [last lesson](add-readme), you have added a:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:183 +msgid "`README` file;" +msgstr "" + +#: ../../tutorials/add-license-coc.md:184 +msgid "`LICENSE` file and a" +msgstr "" + +#: ../../tutorials/add-license-coc.md:185 +msgid "`CODE_OF_CONDUCT` file." +msgstr "" + +#: ../../tutorials/add-license-coc.md:187 +msgid "These are fundamental files needed for every scientific Python package repository. These files help users understand how to use your package and interact with package maintainers." +msgstr "" + +#: ../../tutorials/add-license-coc.md:191 +msgid "In the upcoming lessons, you will:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:193 +msgid "[Add more metadata to your `pyproject.toml` file](pyproject-toml) to support building and publishing your package on PyPI." +msgstr "" + +#: ../../tutorials/add-license-coc.md:194 +msgid "Publish a new version of your Python package to the test PyPI to preview the updated metadata landing page." +msgstr "" + +#: ../../tutorials/add-license-coc.md:199 +#: ../../tutorials/installable-code.md:642 +#: ../../tutorials/publish-conda-forge.md:475 +#: ../../tutorials/publish-pypi.md:394 +msgid "Footnotes" +msgstr "" + +#: ../../tutorials/add-license-coc.md:201 +msgid "https://opensource.org/license/mit/" +msgstr "" + +#: ../../tutorials/add-license-coc.md:202 +msgid "https://opensource.org/license/bsd-3-clause/" +msgstr "" + +#: ../../tutorials/add-readme.md:1 +msgid "Add a README file to your Python package" +msgstr "" + +#: ../../tutorials/add-readme.md:3 +msgid "In the previous lessons you learned:" +msgstr "" + +#: ../../tutorials/add-readme.md:5 +msgid "[What a Python package is](intro.md)" +msgstr "" + +#: ../../tutorials/add-readme.md:6 +msgid "[How to make your code installable](installable-code)" +msgstr "" + +#: ../../tutorials/add-readme.md:7 +msgid "[How to publish your package to (test) PyPI](publish-pypi.md)" +msgstr "" + +#: ../../tutorials/add-readme.md:8 +msgid "[How to publish your package to conda-forge](publish-conda-forge.md)" +msgstr "" + +#: ../../tutorials/add-readme.md:14 +msgid "How to add a **README.md** file to your package." +msgstr "" + +#: ../../tutorials/add-readme.md:15 +msgid "What the core elements of a **README.md** file are." +msgstr "" + +#: ../../tutorials/add-readme.md:18 +msgid "What is a README file?" +msgstr "" + +#: ../../tutorials/add-readme.md:20 +msgid "The `README.md` file is a markdown file located at the root of your project directory that helps a user understand:" +msgstr "" + +#: ../../tutorials/add-readme.md:23 +msgid "You package's name" +msgstr "" + +#: ../../tutorials/add-readme.md:24 +msgid "What the package does. Your README file should clearly state the problem(s) that your software is designed to solve and its target audience." +msgstr "" + +#: ../../tutorials/add-readme.md:25 +msgid "The current development \"state\" of the package (through badges)" +msgstr "" + +#: ../../tutorials/add-readme.md:26 +msgid "How to get started with using your package." +msgstr "" + +#: ../../tutorials/add-readme.md:27 +msgid "How to contribute to your package" +msgstr "" + +#: ../../tutorials/add-readme.md:28 +msgid "How to cite your package" +msgstr "" + +#: ../../tutorials/add-readme.md:30 +msgid "Your **README.md** file is important as it is often the first thing that someone sees before they install your package. The README file is also used to populate your PyPI landing page." +msgstr "" + +#: ../../tutorials/add-readme.md:32 +msgid "Note that there is no specific content structure for README files. However, this tutorial outlines the sections that we suggest that you include in your README file." +msgstr "" + +#: ../../tutorials/add-readme.md:36 +msgid "Create a README.md file for your package" +msgstr "" + +#: ../../tutorials/add-readme.md:38 +msgid "It's time to add a `README.md` file to your project directory." +msgstr "" + +#: ../../tutorials/add-readme.md:40 +msgid "Step 0: Create a README file" +msgstr "" + +#: ../../tutorials/add-readme.md:41 +msgid "To get started, if you don't already have a README.md file in your project directory, create one." +msgstr "" + +#: ../../tutorials/add-readme.md:44 +msgid "If you created your project directory from" +msgstr "" + +#: ../../tutorials/add-readme.md:46 +msgid "a GitHub repository online" +msgstr "" + +#: ../../tutorials/add-readme.md:47 +msgid "using `hatch init`" +msgstr "" + +#: ../../tutorials/add-readme.md:49 +msgid "Then you may already have a README.MD file in your project directory." +msgstr "" + +#: ../../tutorials/add-readme.md:55 +msgid "Step 1: Add the name of your package as the README title" +msgstr "" + +#: ../../tutorials/add-readme.md:57 +msgid "At the top of the `README.md` file, add the name of your package." +msgstr "" + +#: ../../tutorials/add-readme.md:59 +msgid "If you are using markdown it should be a header 1 (H1) tag which is denoted with a single `#` sign." +msgstr "" + +#: ../../tutorials/add-readme.md:61 +msgid "`# Package-title-here`" +msgstr "" + +#: ../../tutorials/add-readme.md:63 +msgid "Step 2: add badges to the top of your README file" +msgstr "" + +#: ../../tutorials/add-readme.md:65 +msgid "It's common for maintainers to add badges to the top of their README files. Badges allow you and your package users to track things like:" +msgstr "" + +#: ../../tutorials/add-readme.md:67 +msgid "Broken documentation and test builds." +msgstr "" + +#: ../../tutorials/add-readme.md:68 +msgid "Versions of your package that are on PyPI and conda." +msgstr "" + +#: ../../tutorials/add-readme.md:69 +msgid "Whether your package has been reviewed and vetted by an organization such as pyOpenSci and/or JOSS." +msgstr "" + +#: ../../tutorials/add-readme.md:71 +msgid "If you have already published your package to pypi.org you can use [shields.io to create a package version badge](https://shields.io/badges/py-pi-version). This badge will dynamically update as you release new versions of your package to PyPI." +msgstr "" + +#: ../../tutorials/add-readme.md:73 +msgid "If not, you can leave the top empty for now and add badges to your README at a later point as they make sense." +msgstr "" + +#: ../../tutorials/add-readme.md:75 +msgid "Step 3: Add a description of what your package does" +msgstr "" + +#: ../../tutorials/add-readme.md:77 +msgid "Below the badges (if you have them), add a section of text that provides an easy-to-understand overview of what your package does." +msgstr "" + +#: ../../tutorials/add-readme.md:81 +msgid "Keep this section short." +msgstr "" + +#: ../../tutorials/add-readme.md:82 +msgid "Try to avoid jargon." +msgstr "" + +#: ../../tutorials/add-readme.md:83 +msgid "Define technical terms that you use to make the description accessible to more people." +msgstr "" + +#: ../../tutorials/add-readme.md:85 +msgid "Remember that the more people understand what your package does, the more people will use it." +msgstr "" + +#: ../../tutorials/add-readme.md:87 +msgid "Step 4: Add package installation instructions" +msgstr "" + +#: ../../tutorials/add-readme.md:89 +msgid "Next, add instructions that tell users how to install your package." +msgstr "" + +#: ../../tutorials/add-readme.md:91 +msgid "For example, can they use pip to install your package? `python -m pip install packagename`" +msgstr "" + +#: ../../tutorials/add-readme.md:94 +msgid "or conda?" +msgstr "" + +#: ../../tutorials/add-readme.md:96 +msgid "`conda install -c conda-forge packagename`." +msgstr "" + +#: ../../tutorials/add-readme.md:98 +msgid "If you haven't yet published your package to pypi.org then you can skip this section and come back and add these instructions later." +msgstr "" + +#: ../../tutorials/add-readme.md:102 +msgid "Step 5: Any additional setup" +msgstr "" + +#: ../../tutorials/add-readme.md:104 +msgid "In some cases, your package users may need to manually install other tools in order to use your package. If that is the case, be sure to add a section on additional setup to your README file." +msgstr "" + +#: ../../tutorials/add-readme.md:109 +msgid "Here, briefly document (or link to documentation for) any additional setup that is required to use your package. This might include:" +msgstr "" + +#: ../../tutorials/add-readme.md:113 +msgid "authentication information, if it is applicable to your package." +msgstr "" + +#: ../../tutorials/add-readme.md:114 +msgid "additional tool installations, such as GDAL." +msgstr "" + +#: ../../tutorials/add-readme.md:117 +msgid "Many packages won't need an additional setup section in their README. In that case you can always skip this section." +msgstr "" + +#: ../../tutorials/add-readme.md:122 +msgid "Step 6: Add a get started section" +msgstr "" + +#: ../../tutorials/add-readme.md:124 +msgid "Next add a get-started section. Within this section, add a small code example that demonstrates importing and using some of the functionality in your package." +msgstr "" + +#: ../../tutorials/add-readme.md:127 +msgid "Provide a fully functional code snippet if possible" +msgstr "" + +#: ../../tutorials/add-readme.md:130 +msgid "It is important to try to make the code examples that you provide your users as useful as possible." +msgstr "" + +#: ../../tutorials/add-readme.md:132 +msgid "Be sure to provide a copy/paste code example that will work as-is when pasted into a Jupyter Notebook or .py file if that is possible." +msgstr "" + +#: ../../tutorials/add-readme.md:134 +msgid "If there are tokens and other steps needed to run your package, be sure to be clear about what those steps are." +msgstr "" + +#: ../../tutorials/add-readme.md:137 +msgid "For the pyosPackage, a short get started demo might look like this:" +msgstr "" + +#: ../../tutorials/add-readme.md:145 +msgid "Or it could simply be a link to a getting started tutorial that you have created. If you don't have this yet, you can leave it empty for the time being." +msgstr "" + +#: ../../tutorials/add-readme.md:148 +msgid "This would also be a great place to add links to tutorials that help users understand how to use your package for common workflows." +msgstr "" + +#: ../../tutorials/add-readme.md:153 +msgid "Step 7: Community section" +msgstr "" + +#: ../../tutorials/add-readme.md:155 +msgid "The community section of your README file is a place to include information for users who may want to engage with your project. This engagement will likely happen on a platform like GitHub or GitLab." +msgstr "" + +#: ../../tutorials/add-readme.md:157 +msgid "In the community section, you will add links to your contributing guide and `CODE_OF_CONDUCT.md`. You will create a [`CODE_OF_CONDUCT.md` file in the next lesson](add-license-coc)." +msgstr "" + +#: ../../tutorials/add-readme.md:160 +msgid "As your package grows you may also have a link to a development guide that contributors and your maintainer team will follow. The development guide outlines how to perform maintenance tasks such as:" +msgstr "" + +#: ../../tutorials/add-readme.md:163 +msgid "running tests" +msgstr "" + +#: ../../tutorials/add-readme.md:164 +msgid "making package releases" +msgstr "" + +#: ../../tutorials/add-readme.md:165 +msgid "building documentation" +msgstr "" + +#: ../../tutorials/add-readme.md:166 +msgid "and more." +msgstr "" + +#: ../../tutorials/add-readme.md:170 +msgid "Step 8: Citation information" +msgstr "" + +#: ../../tutorials/add-readme.md:172 +msgid "Finally it is important to let users know how to cite your package. You can communicate citation information in a few different ways." +msgstr "" + +#: ../../tutorials/add-readme.md:175 +msgid "You can use a tool such as zenodo to create a DOI and associated citation information for your package if it is hosted on a platform such as GitHub. [Check out this short tutorial that covers setting that up.](https://coderefinery.github.io/github-without-command-line/doi/)" +msgstr "" + +#: ../../tutorials/add-readme.md:179 +msgid "Alternatively if you send your package through a peer review process such as the [one lead by pyOpenSci](https://www.pyopensci.org/about-peer-review/index.html). After being accepted by pyOpenSci, if your package is in scope, you can be accepted by the Journal of Open Source Software and get a cross-ref DOI through [our partnership with the Journal of Open Source Software.](https://www.pyopensci.org/about-peer-review/index.html)" +msgstr "" + +#: ../../tutorials/add-readme.md:183 +msgid "The finished README file" +msgstr "" + +#: ../../tutorials/add-readme.md:185 +msgid "Your finished `README.md` file should look something like this:" +msgstr "" + +#: ../../tutorials/add-readme.md:235 +msgid "It's important to consider the information that a new user or contributor might need when creating your `README.md` file. While there is no perfect template, above is a set of recommendations as you are just getting started. You may find the need for other elements to be added to this file as you further develop your package and as a community begins to use your package." +msgstr "" + +#: ../../tutorials/add-readme.md:241 +msgid "In the [next lesson](add-license-coc.md), you will add a LICENSE file to your Python package. A license file is critical as it tells users how they legally can (and can't) use your package. It also:" +msgstr "" + +#: ../../tutorials/add-readme.md:245 +msgid "Builds trust with your users" +msgstr "" + +#: ../../tutorials/add-readme.md:246 +msgid "Discourages misuse of your package and associated code" +msgstr "" + +#: ../../tutorials/command-line-reference.md:1 +#: ../../tutorials/intro.md:54 +msgid "Command Line Reference Guide" +msgstr "" + +#: ../../tutorials/command-line-reference.md:4 +msgid "**What these tables are:** These tables summarize the command line inputs (e.g., `pipx install hatch`, `hatch build`) necessary to complete all steps in the package creation process, from installing Hatch to publishing the package on PyPI and conda-forge." +msgstr "" + +#: ../../tutorials/command-line-reference.md:6 +msgid "**What these tables are not:** These tables do not cover the manual/non-automated steps (e.g., create PyPI account, create PyPI API token) you have to complete throughout the package creation process." +msgstr "" + +#: ../../tutorials/command-line-reference.md:8 +msgid "**Operating system note:** The current iteration of this guide has been tested on the Windows OS only. Many commands are Windows-specific. OS-specific commands are indicated with parentheses after the description of the command, e.g., [COMMAND_DESCRIPTION] (Windows). Corresponding commands for macOS and Linux will be added in the future." +msgstr "" + +#: ../../tutorials/command-line-reference.md:11 +msgid "Environment Setup" +msgstr "" + +#: ../../tutorials/command-line-reference.md:33 +msgid "Package Development" +msgstr "" + +#: ../../tutorials/command-line-reference.md:52 +msgid "Package Publishing" +msgstr "" + +#: ../../tutorials/command-line-reference.md:71 +msgid "Versions and Environments" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:1 +msgid "Get to Know Hatch" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:3 +msgid "Our Python packaging tutorials use the tool [Hatch](https://hatch.pypa.io/latest/). While there are [many great packaging tools](/package-structure-code/python-package-build-tools) out there, we have selected Hatch because:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:8 +msgid "It is an end-to-end tool that supports most of the steps required to create a quality Python package. Beginners will have fewer tools to learn if they use Hatch." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:11 +msgid "It supports different build back-ends if you ever need to compile code in other languages." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:13 +msgid "As a community, pyOpenSci has decided that Hatch is a user-friendly tool that supports many different scientific Python use cases." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:16 +msgid "In this tutorial, you will install and get to know Hatch a bit more before starting to use it." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:19 +msgid "You need two things to successfully complete this tutorial:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:21 +msgid "You need Python installed." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:22 +msgid "You need Hatch installed." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:25 +msgid "If you don't already have Python installed on your computer, Hatch will do it for you when you install Hatch." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:29 +msgid "Install Hatch" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:31 +msgid "To begin, follow the operating-system-specific instructions below to install Hatch." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:0 +msgid "MAC" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:38 +msgid "Follow the instructions [here](https://hatch.pypa.io/latest/install/#installers)." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:40 +msgid "Download the latest GUI installer for MAC [hatch-universal.pkg](https://github.com/pypa/hatch/releases/latest/download/hatch-universal.pkg)." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:41 +msgid "Run the installer and follow the setup instructions." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:42 +msgid "If your terminal is open, then restart it." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:0 +msgid "Windows" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:48 +msgid "In your browser, download the correct `.msi` file for your system: [hatch-x64.msi](https://github.com/pypa/hatch/releases/latest/download/hatch-x64.msi)" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:50 +msgid "Run your downloaded installer file and follow the on-screen instructions." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:0 +msgid "Linux" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:56 +msgid "We suggest that you install Hatch using pipx on Linux. however, if you prefer another method, check out the [Hatch installation documentation](https://hatch.pypa.io/latest/install/) for other methods." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:70 +msgid "Hatch can also be installed directly using [pip](https://hatch.pypa.io/latest/install/#pip) or [conda](https://hatch.pypa.io/latest/install/#conda). We encourage you to follow the instructions above because we have found that the Hatch installers for Windows and Mac are the easiest and most efficient." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:74 +msgid "Our Linux users have found success installing Hatch with pipx if they already use apt install." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:77 +msgid "Both approaches (using a graphical installer on Windows/Mac and pipx) ensure that you have Hatch installed globally. A global install means that Hatch is available across all of your Python environments on your computer." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:82 +msgid "Check that hatch installed correctly" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:84 +msgid "Once you have completed the installation instructions above, you can open your terminal, and make sure that Hatch installed correctly using the command below:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:92 +msgid "*Note the version number output of `hatch --version` will likely be different from the output above in this tutorial.*" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:95 +msgid "Configure Hatch" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:97 +msgid "Once you have installed Hatch, you can customize its configuration. This includes setting the default name and setup for every package you create. While this step is not required, we suggest that you do it." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:101 +msgid "Hatch stores your configuration in a [`config.toml` file](https://hatch.pypa.io/latest/config/project-templates/)." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:103 +msgid "While you can update the `config.toml` file through the command line, it might be easier to look at and update it in a text editor if you are using it for the first time." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:107 +msgid "Step 1: Open and Edit Your `config.toml` File" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:109 +msgid "To open the config file in your file browser, run the following command in your shell:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:112 +msgid "`hatch config explore`" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:114 +msgid "This will open up a directory window that allows you to double-click on the file and open it in your favorite text editor." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:117 +msgid "You can also retrieve the location of the Hatch config file by running the following command in your shell:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:125 +msgid "Step 2 - update your email and name" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:127 +msgid "Once the file is open, update the [template] table of the `config.toml` file with your name and email. This information will be used in any `pyproject.toml` metadata files that you create using Hatch." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:137 +msgid "Step 3" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:139 +msgid "Next, set tests to false in the `[template.plugins.default]` table." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:141 +msgid "While tests are important, setting the tests configuration in Hatch to `true` will create a more complex `pyproject.toml` file. You won't need to use this feature in this beginner friendly tutorial series but we will introduce it in later tutorials." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:146 +msgid "Your `config.toml` file should look something like the one below." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:184 +msgid "Also notice that the default license option is MIT. While we will discuss license in more detail in a later lesson, the MIT license is the recommended permissive license from [choosealicense.com](https://www.choosealicense.com) and as such we will use it for this tutorial series." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:190 +msgid "You are of course welcome to select another license." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:192 +#: ../../tutorials/installable-code.md:22 +#: ../../tutorials/installable-code.md:411 +#: ../../tutorials/installable-code.md:502 +#: ../../tutorials/intro.md:235 +#: ../../tutorials/publish-pypi.md:3 +#: ../../tutorials/publish-pypi.md:178 +#: ../../tutorials/publish-pypi.md:350 +#: ../../tutorials/pyproject-toml.md:718 +msgid "Todo" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:193 +msgid "I think we'd need the SPDX license options here if they want to chose bsd-3 for instance" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:196 +msgid "Step 4: Close the config file and run `hatch config show`" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:198 +msgid "Once you have completed the steps above run the following command in your shell." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:200 +msgid "`hatch config show`" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:202 +msgid "`hatch config show` will print out the contents of your `config.toml` file in your shell. Look at the values and ensure that your name, email is set. Also make sure that `tests=false`." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:206 +msgid "Hatch features" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:208 +msgid "Hatch offers a suite of features that will make creating, publishing and maintaining your Python package easier." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:211 +msgid "Comparison to other tools" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:213 +msgid "[We compared Hatch to several of the other popular packaging tools in the ecosystem including flit, pdm and poetry. Learn more here](package-features)" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:216 +msgid "[More on Hatch here](hatch)" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:218 +msgid "A few features that Hatch offers" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:220 +msgid "It will convert metadata stored in a `setup.py` or `setup.cfg` file to a pyproject.toml file for you (see [Migrating setup.py to pyproject.toml using Hatch](setup-py-to-pyproject-toml.md ))" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:222 +msgid "It will help you by storing configuration information for publishing to PyPI after you've entered it once." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:224 +msgid "Use `hatch -h` to see all of the available commands." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:226 +msgid "What's next" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:228 +msgid "In the next lesson you'll learn how to package and make your code installable using Hatch." +msgstr "" + +#: ../../tutorials/installable-code.md:6 +msgid "Make your Python code installable" +msgstr "" + +#: ../../tutorials/installable-code.md:8 +msgid "What we previously covered" +msgstr "" + +#: ../../tutorials/installable-code.md:9 +msgid "[In the previous lesson](intro), you learned about what a Python package is. You also learned about the [benefits of creating a Python package](package-benefits)." +msgstr "" + +#: ../../tutorials/installable-code.md:13 +msgid "Your next step in our packaging tutorial series is to create a Python package that is installable both locally and remotely from a website such as GitHub (or GitLab). The package that you create in this lesson will have the bare minimum elements needed to be installable into a Python environment." +msgstr "" + +#: ../../tutorials/installable-code.md:18 +msgid "Making your code installable is an important steps towards creating a full Python package that is directly installable from PyPI." +msgstr "" + +#: ../../tutorials/installable-code.md:23 +msgid "Is it clear where to add commands? Bash vs. Python console Bash vs. Zsh is different" +msgstr "" + +#: ../../tutorials/installable-code.md:25 +msgid "Does this lesson run as expected on windows and mac?" +msgstr "" + +#: ../../tutorials/installable-code.md:26 +msgid "ADD: note about what makes something \"package worthy\", with a common misconception being that a package should be production-ready code that's valuable to a broad audience. This may not be a pervasive misconception in Python, but a quick break-out with an explanation of what a package can consist of would be helpful." +msgstr "" + +#: ../../tutorials/installable-code.md:31 +msgid "Diagram showing the basic steps to creating an installable package. There are 4 boxes with arrows pointing towards the right. The boxes read, your code, create package structure, add metadata to pyproject.toml and pip install package." +msgstr "" + +#: ../../tutorials/installable-code.md:33 +msgid "A basic installable package needs a few things: code, a [specific package file structure](https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-structure.html) and a `pyproject.toml` containing your package's name and version. Once you have these items in the correct directory structure, you can pip install your package into any environment on your computer. You will learn how to create a basic installable package in this lesson." +msgstr "" + +#: ../../tutorials/installable-code.md:37 +msgid "About this lesson" +msgstr "" + +#: ../../tutorials/installable-code.md:43 +msgid "How to make your code installable into any Python environment both locally and from GitHub" +msgstr "" + +#: ../../tutorials/installable-code.md:44 +msgid "How to create a basic `pyproject.toml` file that includes package dependencies and metadata. This file is required to make your package installable." +msgstr "" + +#: ../../tutorials/installable-code.md:45 +msgid "How to declare a [build backend](build_backends) which will be used to [build](build-package) and install your package" +msgstr "" + +#: ../../tutorials/installable-code.md:46 +msgid "How to install your package in editable mode for interactive development" +msgstr "" + +#: ../../tutorials/installable-code.md:48 +msgid "**What you need to complete this lesson**" +msgstr "" + +#: ../../tutorials/installable-code.md:50 +msgid "To complete this lesson you will need a local Python environment and shell on your computer. You will also need to have [Hatch installed](get-to-know-hatch)." +msgstr "" + +#: ../../tutorials/installable-code.md:53 +msgid "If you are using Windows or are not familiar with Shell, you may want to check out the Carpentries shell lesson[^shell-lesson]. Windows users will likely need to configure a tool for any Shell and git related steps." +msgstr "" + +#: ../../tutorials/installable-code.md:55 +msgid "**What comes next**" +msgstr "" + +#: ../../tutorials/installable-code.md:57 +msgid "In the upcoming lessons you will learn how to:" +msgstr "" + +#: ../../tutorials/installable-code.md:59 +msgid "[Publish your package to PyPI](publish-pypi)" +msgstr "" + +#: ../../tutorials/installable-code.md:60 +msgid "Add a README file to your package to support community use" +msgstr "" + +#: ../../tutorials/installable-code.md:61 +msgid "Add additional project metadata to your package to support PyPI publication" +msgstr "" + +#: ../../tutorials/installable-code.md:67 +msgid "This diagram has two smaller boxes with arrows pointing to the right to a Python environment. The small boxes read your-package and pip install package. The environment box on the right reads - your Python environment. It them lists your-package along with a few other core packages such as Matplotlib, NumPy, Pandas, Xarray and GeoPandas." +msgstr "" + +#: ../../tutorials/installable-code.md:69 +msgid "Making your code installable is the first step towards creating a publishable Python package. Once your code is installable, it is a Python package and can be added to any Python environment on your computer and imported in the same way that you might import a package such as Pandas or GeoPandas. If your code is on GitHub or GitLab you can also install it directly from there." +msgstr "" + +#: ../../tutorials/installable-code.md:74 +msgid "About the Python package directory structure" +msgstr "" + +#: ../../tutorials/installable-code.md:76 +msgid "To make your Python code installable you need to create a specific directory structure with the following elements:" +msgstr "" + +#: ../../tutorials/installable-code.md:78 +msgid "A `pyproject.toml` file." +msgstr "" + +#: ../../tutorials/installable-code.md:79 +msgid "A specific directory structure." +msgstr "" + +#: ../../tutorials/installable-code.md:80 +msgid "Some code." +msgstr "" + +#: ../../tutorials/installable-code.md:81 +msgid "An `__init__.py` file in your code directory." +msgstr "" + +#: ../../tutorials/installable-code.md:83 +msgid "The directory structure you'll create in this lesson will look like this:" +msgstr "" + +#: ../../tutorials/installable-code.md:95 +msgid "About the basic package directory structure" +msgstr "" + +#: ../../tutorials/installable-code.md:97 +msgid "Notice a few things about the above layout:" +msgstr "" + +#: ../../tutorials/installable-code.md:99 +msgid "Your package code lives within a `src/packagename` directory. We suggest that you use `src` (short for **source code**) directory as it [ensures that you are running tests on the installed version of your code](https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-structure.html#the-src-layout-and-testing)." +msgstr "" + +#: ../../tutorials/installable-code.md:100 +msgid "Within the `src` directory you have a package directory called `pyospackage`. Use the name of your package for that directory name. This will be the name for importing your package in Python code once installed." +msgstr "" + +#: ../../tutorials/installable-code.md:101 +msgid "In your package directory, you have an `__init__.py` file and all of your Python modules. You will learn more about the `__init__.py` file below." +msgstr "" + +#: ../../tutorials/installable-code.md:102 +msgid "The `pyproject.toml` file lives at the root directory of your package." +msgstr "" + +#: ../../tutorials/installable-code.md:103 +msgid "The name of the root directory for the package is **pyospackage** which is the name of the package. This is not a requirement but you will often see that the GitHub / GitLab repository and the root directory name are the same as the package name." +msgstr "" + +#: ../../tutorials/installable-code.md:105 +msgid "What is an `__init__.py` file?" +msgstr "" + +#: ../../tutorials/installable-code.md:107 +msgid "The `__init__.py` file tells Python that a directory should be treated as a Python package. As such, a directory with an `__init__.py` file can be imported directly into Python. The `__init__.py` file does not need to contain any code in order for Python to recognize it; it can be empty." +msgstr "" + +#: ../../tutorials/installable-code.md:111 +msgid "For example, following the file structure example above which has an `__init__.py` file within it, you can run:" +msgstr "" + +#: ../../tutorials/installable-code.md:117 +#: ../../tutorials/pyproject-toml.md:48 +msgid "What is a pyproject.toml file?" +msgstr "" + +#: ../../tutorials/installable-code.md:119 +msgid "The **pyproject.toml** file is:" +msgstr "" + +#: ../../tutorials/installable-code.md:121 +msgid "Where you define your project's metadata (including its name, authors, license, etc)" +msgstr "" + +#: ../../tutorials/installable-code.md:122 +msgid "Where you define dependencies (the packages that it depends on)" +msgstr "" + +#: ../../tutorials/installable-code.md:123 +msgid "Used to specify and configure what build backend you want to use to [build your package](../package-structure-code/python-package-distribution-files-sdist-wheel)." +msgstr "" + +#: ../../tutorials/installable-code.md:125 +msgid "After the `__init__.py` and `pyproject.toml` files have been added, your package can be built and distributed as an installable Python package using tools such as pip. Note that the `pyproject.toml` file needs to have a few basic items defined for the package to be installable including:" +msgstr "" + +#: ../../tutorials/installable-code.md:131 +msgid "The `build-backend` that you want to use," +msgstr "" + +#: ../../tutorials/installable-code.md:132 +msgid "The project `name` and `version`." +msgstr "" + +#: ../../tutorials/installable-code.md:134 +msgid "Why the pyproject.toml file is important" +msgstr "" + +#: ../../tutorials/installable-code.md:138 +msgid "The `pyproject.toml` file replaces some of the functionality of both the `setup.py` file and `setup.cfg` files. If you try to pip install a package with no `pyproject.toml` you will get the following error:" +msgstr "" + +#: ../../tutorials/installable-code.md:150 +msgid "Note about `setup.py`" +msgstr "" + +#: ../../tutorials/installable-code.md:154 +msgid "If your project already defines a `setup.py` file, Hatch can be used to automatically create the `pyproject.toml`." +msgstr "" + +#: ../../tutorials/installable-code.md:155 +msgid "See [Using Hatch to Migrate setup.py to a pyproject.toml ](setup-py-to-pyproject-toml.md)" +msgstr "" + +#: ../../tutorials/installable-code.md:161 +msgid "Time to create your Python package!" +msgstr "" + +#: ../../tutorials/installable-code.md:163 +msgid "Now that you understand the basics of the Python package directory structure, and associated key files (`__init__.py` and `pyproject.toml`), it's time to create your Python package! Below you will create a directory structure similar to the structure described above using Hatch." +msgstr "" + +#: ../../tutorials/installable-code.md:167 +msgid "Step 1: Set Up the Package Directory Structure" +msgstr "" + +#: ../../tutorials/installable-code.md:169 +msgid "Open your shell or preferred terminal." +msgstr "" + +#: ../../tutorials/installable-code.md:170 +msgid "Use the shell `cd` command to navigate in your shell to the location where you'd like your package directory to live. Hatch will create the package directory for you" +msgstr "" + +#: ../../tutorials/installable-code.md:171 +msgid "Choose a name for your package. The name should:" +msgstr "" + +#: ../../tutorials/installable-code.md:172 +msgid "Have no spaces (*Required*)" +msgstr "" + +#: ../../tutorials/installable-code.md:173 +msgid "Use all lowercase characters (*Recommended*). For this tutorial we will use `pyospackage`." +msgstr "" + +#: ../../tutorials/installable-code.md:174 +msgid "Only use letter and the characters _ or - in the name. This means that the name `pyos*package` is not an acceptable name. However, the names `pyos_package` or `pyos-package` both are ok" +msgstr "" + +#: ../../tutorials/installable-code.md:176 +msgid "Hatch and project names" +msgstr "" + +#: ../../tutorials/installable-code.md:177 +msgid "Hatch makes some decisions for your project's name when you run `hatch new`" +msgstr "" + +#: ../../tutorials/installable-code.md:179 +msgid "These include using:" +msgstr "" + +#: ../../tutorials/installable-code.md:180 +msgid "dashes for the top level directory" +msgstr "" + +#: ../../tutorials/installable-code.md:181 +msgid "dashes for the project name in the pyproject.toml" +msgstr "" + +#: ../../tutorials/installable-code.md:182 +msgid "underscores for the package directory name" +msgstr "" + +#: ../../tutorials/installable-code.md:196 +msgid "If you use a name with underscores, Hatch will return the same thing:" +msgstr "" + +#: ../../tutorials/installable-code.md:209 +msgid "In both of the examples above the project name in the pyproject.toml file that hatch creates is `pyos-package`." +msgstr "" + +#: ../../tutorials/installable-code.md:213 +msgid "Next run:" +msgstr "" + +#: ../../tutorials/installable-code.md:228 +msgid "Your final project directory structure should look like this:" +msgstr "" + +#: ../../tutorials/installable-code.md:243 +msgid "Step 2: Add module to your package" +msgstr "" + +#: ../../tutorials/installable-code.md:245 +msgid "A Python module refers to a `.py` file containing the code that you want your package to access and run. Within the `pyospackage` subdirectory, add at least one Python modules (.py files)." +msgstr "" + +#: ../../tutorials/installable-code.md:247 +msgid "If you don't have code already and are just learning how to create a Python package, then create an empty `add_numbers.py` file. You will populate the `add_numbers.py` file with code provided below." +msgstr "" + +#: ../../tutorials/installable-code.md:250 +msgid "Python modules and the `__init__.py` file" +msgstr "" + +#: ../../tutorials/installable-code.md:254 +msgid "When you see the word module, we are referring to a `.py` file containing Python code." +msgstr "" + +#: ../../tutorials/installable-code.md:257 +msgid "The `__init__.py` allows Python to recognize that a directory contains at least one module that may be imported and used in your code. A package can have multiple modules[^python-modules]." +msgstr "" + +#: ../../tutorials/installable-code.md:261 +msgid "Your project directory should now look like this:" +msgstr "" + +#: ../../tutorials/installable-code.md:271 +msgid "Step 3: Add code to your module" +msgstr "" + +#: ../../tutorials/installable-code.md:273 +msgid "If you are following along and making a Python package from scratch then you can add the code below to your `add_numbers.py` module. The function below adds two integers together and returns the result. Notice that the code below has a few features that we will review in future tutorials:" +msgstr "" + +#: ../../tutorials/installable-code.md:275 +msgid "It has a [numpy-style docstring](numpy-docstring)" +msgstr "" + +#: ../../tutorials/installable-code.md:276 +msgid "It uses [typing](type-hints)" +msgstr "" + +#: ../../tutorials/installable-code.md:278 +msgid "Python can support many different docstrings formats depending on the documentation build system you wish to use. The most popular supported formats for documenting Python objects are NumPy Style Docstring[^numpydoc], Google Style Docstring[^googledoc], and the Epytext Style Docstrings[^epytextdoc]." +msgstr "" + +#: ../../tutorials/installable-code.md:280 +msgid "**pyOpenSci recommends using the NumPy Docstring convention.**" +msgstr "" + +#: ../../tutorials/installable-code.md:282 +msgid "If you aren't familiar with docstrings or typing yet, that is ok. You can review [this page in the pyOpenSci packaging guide](https://www.pyopensci.org/python-package-guide/documentation/write-user-documentation/document-your-code-api-docstrings.html) for an overview of both topics." +msgstr "" + +#: ../../tutorials/installable-code.md:311 +msgid "Step 4: Modify metadata in your `pyproject.toml` file" +msgstr "" + +#: ../../tutorials/installable-code.md:313 +msgid "Next, you will modify some of the metadata (information) that Hatch adds to your `pyproject.toml` file. You are are welcome to copy the file we have in our [example pyospackage GitHub repository](https://github.com/pyOpenSci/pyosPackage)." +msgstr "" + +#: ../../tutorials/installable-code.md:317 +msgid "Brief overview of the TOML file" +msgstr "" + +#: ../../tutorials/installable-code.md:320 +msgid "[The TOML format](https://toml.io/en/) consists of tables and variables. Tables are sections of information denoted by square brackets:" +msgstr "" + +#: ../../tutorials/installable-code.md:322 +msgid "`[this-is-a-table]`." +msgstr "" + +#: ../../tutorials/installable-code.md:324 +msgid "Tables can contain variables within them defined by an variable name and an `=` sign. For instance, a `build-system` table most often holds two (2) variables:" +msgstr "" + +#: ../../tutorials/installable-code.md:327 +msgid "`requires = `, which tells a build tool what tools it needs to install prior to building your package. In this case [hatchling](https://pypi.org/project/hatchling/)" +msgstr "" + +#: ../../tutorials/installable-code.md:329 +msgid "`build-backend = `, which is used to define the specific build-backend name, (in this example we are using `hatchling.build`)." +msgstr "" + +#: ../../tutorials/installable-code.md:338 +msgid "TOML organizes data structures, defining relationships within a configuration file." +msgstr "" + +#: ../../tutorials/installable-code.md:341 +msgid "[Learn more about the pyproject.toml format here.](../package-structure-code/pyproject-toml-python-package-metadata)" +msgstr "" + +#: ../../tutorials/installable-code.md:345 +msgid "You will learn more about the `pyproject.toml` format in the [next lesson when you add additional metadata / information to this file.](pyproject-toml.md)" +msgstr "" + +#: ../../tutorials/installable-code.md:348 +msgid "Open up the `pyproject.toml` file that Hatch created in your favorite text editor. It should look something like the example below." +msgstr "" + +#: ../../tutorials/installable-code.md:390 +msgid "Edit the file as follows:" +msgstr "" + +#: ../../tutorials/installable-code.md:392 +msgid "Delete `dynamic = [\"version\"]`: This sets up dynamic versioning based on tags stored in your git commit history. We will walk through implementing this in a later lesson." +msgstr "" + +#: ../../tutorials/installable-code.md:393 +msgid "Add `version = \"0.1\"` in the place of `dynamic = [\"version\"]` which you just deleted. This sets up manual versioning." +msgstr "" + +#: ../../tutorials/installable-code.md:394 +msgid "Fill in the description if it doesn't already exist." +msgstr "" + +#: ../../tutorials/installable-code.md:404 +msgid "Remove the `[tool.hatch.version]` table from the bottom of the file." +msgstr "" + +#: ../../tutorials/installable-code.md:412 +msgid "When this lesson exists, uncomment this admonition You will learn how to automate defining a package version using git tags in the version and release your package lesson." +msgstr "" + +#: ../../tutorials/installable-code.md:417 +msgid "OPTIONAL: Adjust project classifiers" +msgstr "" + +#: ../../tutorials/installable-code.md:419 +msgid "Hatch by default provides a list of classifiers that define what Python versions your package supports. These classifiers do not in any way impact your package's build and are primarily intended to be used when you publish your package to PyPI." +msgstr "" + +#: ../../tutorials/installable-code.md:424 +msgid "If you don't plan on publishing to PyPI, you can skip this section. However, if you wish, you can clean it up a bit." +msgstr "" + +#: ../../tutorials/installable-code.md:427 +msgid "To begin:" +msgstr "" + +#: ../../tutorials/installable-code.md:429 +msgid "Remove support for Python 3.8" +msgstr "" + +#: ../../tutorials/installable-code.md:430 +msgid "Within the `[project]` table, update `requires-python = \">3.8\"` to `requires-python = \">3.9\"`" +msgstr "" + +#: ../../tutorials/installable-code.md:432 +msgid "Since you are creating a pure Python package in this lesson, you can remove the following classifiers:" +msgstr "" + +#: ../../tutorials/installable-code.md:442 +msgid "Your new pyproject.toml file should now look something like this:" +msgstr "" + +#: ../../tutorials/installable-code.md:477 +msgid "The bare minimum needed in a pyproject.toml file" +msgstr "" + +#: ../../tutorials/installable-code.md:480 +msgid "The core information that you need in a `pyproject.toml` file in order to publish on PyPI is your **package's name** and the **version**. However, we suggest that you flesh out your metadata early on in the `pyproject.toml` file." +msgstr "" + +#: ../../tutorials/installable-code.md:482 +msgid "Once you have your project metadata in the pyproject.toml file, you will rarely update it. In the next lesson you'll add more metadata and structure to this file." +msgstr "" + +#: ../../tutorials/installable-code.md:486 +msgid "Step 5: Install your package locally" +msgstr "" + +#: ../../tutorials/installable-code.md:488 +msgid "At this point you should have:" +msgstr "" + +#: ../../tutorials/installable-code.md:490 +msgid "A project directory structure with a `pyproject.toml` file at the root" +msgstr "" + +#: ../../tutorials/installable-code.md:491 +msgid "A package directory containing an empty `__init__.py` file and" +msgstr "" + +#: ../../tutorials/installable-code.md:492 +msgid "At least one Python module (e.g. `add_numbers.py`)" +msgstr "" + +#: ../../tutorials/installable-code.md:494 +msgid "You are now ready to install (and build) your Python package!" +msgstr "" + +#: ../../tutorials/installable-code.md:496 +msgid "While you can do this using hatch, we are going to use pip for this lesson, so you can see how to install your tool into your preferred environment." +msgstr "" + +#: ../../tutorials/installable-code.md:498 +msgid "First open your preferred shell (Windows users may be using something like gitbash) and `cd` into your project directory if you are not already there." +msgstr "" + +#: ../../tutorials/installable-code.md:499 +msgid "Activate the Python environment that you wish to use." +msgstr "" + +#: ../../tutorials/installable-code.md:500 +msgid "Run `python -m pip install -e .`" +msgstr "" + +#: ../../tutorials/installable-code.md:503 +msgid "Add this back in when the lesson is published" +msgstr "" + +#: ../../tutorials/installable-code.md:504 +msgid "Activate the Python environment that you wish to use. If you need help with working with virtual environments check out this lesson (add link)." +msgstr "" + +#: ../../tutorials/installable-code.md:530 +msgid "What does `python -m pip install -e .` do?" +msgstr "" + +#: ../../tutorials/installable-code.md:533 +msgid "Let's break down `python -m pip install -e .`" +msgstr "" + +#: ../../tutorials/installable-code.md:535 +msgid "`python -m pip install -e .` installs your package into the current active Python environment in **editable mode** (`-e`). Installing your package in editable mode, allows you to work on your code and then test the updates interactively in your favorite Python interface. One important caveat of editable mode is that every time you update your code, you may need to restart Python." +msgstr "" + +#: ../../tutorials/installable-code.md:540 +msgid "If you wish to install the package regularly (not in editable mode) you can use:" +msgstr "" + +#: ../../tutorials/installable-code.md:543 +msgid "`python -m pip install . `" +msgstr "" + +#: ../../tutorials/installable-code.md:545 +msgid "**Using `python -m` when calling `pip`**" +msgstr "" + +#: ../../tutorials/installable-code.md:547 +msgid "Above, you use`python -m` to call the version of pip installed into your current active environment. `python -m` is important to ensure that you are calling the version of pip installed in your current environment." +msgstr "" + +#: ../../tutorials/installable-code.md:552 +msgid "Look for pyospackage in your environment" +msgstr "" + +#: ../../tutorials/installable-code.md:554 +msgid "Once you have installed your package, you can view it in your current environment. If you are using `venv` or `conda`, `pip` list will allow you to see your current package installations." +msgstr "" + +#: ../../tutorials/installable-code.md:558 +msgid "Note that because pyospackage is installed in editable mode (`-e`) pip will show you the directory path to your project's code" +msgstr "" + +#: ../../tutorials/installable-code.md:586 +msgid "Step 6: Test out your new package" +msgstr "" + +#: ../../tutorials/installable-code.md:588 +msgid "After installing your package, type “python” at the command prompt in your chosen terminal to start a Python session in your active Python environment." +msgstr "" + +#: ../../tutorials/installable-code.md:591 +msgid "You can now import your package and access the `add_num` function." +msgstr "" + +#: ../../tutorials/installable-code.md:603 +msgid "Installing packages from GitHub" +msgstr "" + +#: ../../tutorials/installable-code.md:605 +msgid "If you wish to share your code without publishing to PyPI you can always install packages directly from GitHub using the syntax:" +msgstr "" + +#: ../../tutorials/installable-code.md:612 +msgid "To make your package GitHub installable, you can:" +msgstr "" + +#: ../../tutorials/installable-code.md:614 +msgid "Create a new GitHub repository" +msgstr "" + +#: ../../tutorials/installable-code.md:615 +msgid "Push the contents of the project directory that you created above, to GitHub" +msgstr "" + +#: ../../tutorials/installable-code.md:616 +msgid "Finally install the package from GitHub using the command above. When you use the command above, don't forget to substitute the user, repo, and branch_or_tag with your specific values." +msgstr "" + +#: ../../tutorials/installable-code.md:618 +msgid "For instance below you install the pyospackage from the main branch of the pyOpenSci repository." +msgstr "" + +#: ../../tutorials/installable-code.md:621 +msgid "`python -m pip install git+https://github.com/user/repo.git@branch_or_tag`" +msgstr "" + +#: ../../tutorials/installable-code.md:625 +msgid "Congratulations! You created your first Python package" +msgstr "" + +#: ../../tutorials/installable-code.md:627 +msgid "You did it! You have now created a Python package that you can install into any Python environment." +msgstr "" + +#: ../../tutorials/installable-code.md:630 +msgid "In the upcoming lessons you will:" +msgstr "" + +#: ../../tutorials/installable-code.md:632 +msgid "Learn how to [build and publish your Python package to (test) PyPI](publish-pypi)" +msgstr "" + +#: ../../tutorials/installable-code.md:633 +msgid "Add a README file and LICENSE to your package" +msgstr "" + +#: ../../tutorials/installable-code.md:634 +msgid "Add more metadata to your `pyproject.toml` file to support PyPI publication." +msgstr "" + +#: ../../tutorials/installable-code.md:635 +msgid "learn how to publish to **conda-forge** from **PyPI**." +msgstr "" + +#: ../../tutorials/installable-code.md:637 +msgid "Add a [README file](add-readme.md) and [LICENSE](add-license-coc.md) to your package" +msgstr "" + +#: ../../tutorials/installable-code.md:638 +msgid "[Add more metadata to your `pyproject.toml`](pyproject-toml.md) file to support PyPI publication." +msgstr "" + +#: ../../tutorials/installable-code.md:639 +msgid "[Learn how to build your package distribution](publish-pypi) files (**sdist** and **wheel**) and publish to **test PyPI**." +msgstr "" + +#: ../../tutorials/installable-code.md:640 +msgid "Finally you will learn how to [publish to **conda-forge**](publish-conda-forge) from **PyPI**." +msgstr "" + +#: ../../tutorials/installable-code.md:644 +msgid "[Carpentries shell lesson](https://swcarpentry.github.io/shell-novice/)" +msgstr "" + +#: ../../tutorials/installable-code.md:646 +msgid "[Python module docs](https://docs.python.org/3/tutorial/modules.html#packages)" +msgstr "" + +#: ../../tutorials/installable-code.md:648 +msgid "[Numpy style docs](https://numpydoc.readthedocs.io/en/latest/format.html)" +msgstr "" + +#: ../../tutorials/installable-code.md:647 +msgid "[Google docstring style](https://google.github.io/styleguide/pyguide.html)" +msgstr "" + +#: ../../tutorials/installable-code.md:649 +msgid "[epydoc](https://epydoc.sourceforge.net/epytext.html)" +msgstr "" + +#: ../../tutorials/intro.md:28 +#: ../../tutorials/setup-py-to-pyproject-toml.md:24 +msgid "Get to know Hatch" +msgstr "" + +#: ../../tutorials/intro.md:28 +msgid "Python Packaging Tutorial Setup" +msgstr "" + +#: ../../tutorials/intro.md:35 +#: ../../tutorials/intro.md:80 +msgid "What is a Python package?" +msgstr "" + +#: ../../tutorials/intro.md:35 +msgid "Create a Python package" +msgstr "" + +#: ../../tutorials/intro.md:35 +msgid "Publish to PyPI" +msgstr "" + +#: ../../tutorials/intro.md:35 +msgid "Publish to conda-forge" +msgstr "" + +#: ../../tutorials/intro.md:35 +msgid "Create and publish a Python Package" +msgstr "" + +#: ../../tutorials/intro.md:45 +msgid "Add README file" +msgstr "" + +#: ../../tutorials/intro.md:45 +msgid "Add a license & code of conduct" +msgstr "" + +#: ../../tutorials/intro.md:45 +msgid "Update metadata in pyproject.toml" +msgstr "" + +#: ../../tutorials/intro.md:45 +msgid "Project information files & metadata" +msgstr "" + +#: ../../tutorials/intro.md:54 +msgid "Reference Guides" +msgstr "" + +#: ../../tutorials/intro.md:61 +msgid "Migrate setup.py to a pyproject.toml using Hatch" +msgstr "" + +#: ../../tutorials/intro.md:61 +msgid "Hatch for Existing Packages" +msgstr "" + +#: ../../tutorials/intro.md:2 +msgid "Python packaging 101" +msgstr "" + +#: ../../tutorials/intro.md:4 +msgid "_A start to finish beginner-friendly tutorial_" +msgstr "" + +#: ../../tutorials/intro.md:6 +msgid "Welcome to the pyOpenSci Python packaging tutorial series. The lessons on the upcoming pages walk you through the core steps needed to create a Python package." +msgstr "" + +#: ../../tutorials/intro.md:12 +msgid "Diagram showing the lessons in our packaging tutorial. There are 6 total - what is a Python package, make code pip installable, publish your package to PyPI, add a README and LICENSE file, add metadata for PyPI and finally publish to conda forge." +msgstr "" + +#: ../../tutorials/intro.md:14 +msgid "This lesson is the first in a series of lessons to help you get started with Python packaging." +msgstr "" + +#: ../../tutorials/intro.md:17 +msgid "Who are these tutorials for?" +msgstr "" + +#: ../../tutorials/intro.md:19 +msgid "The content in this tutorial series is beginner friendly and assumes that you have not created a Python package before. However, the content will still be valuable if you are interested in better understanding the steps involved in creating a Python package." +msgstr "" + +#: ../../tutorials/intro.md:24 +msgid "In this series you will learn about the core elements that you need to publish your package to the [Python Package Index (PyPI)](https://pypi.org/)." +msgstr "" + +#: ../../tutorials/intro.md:26 +msgid "In the second series, you will learn about infrastructure and documentation needed to support package maintenance." +msgstr "" + +#: ../../tutorials/intro.md:68 +#: ../../tutorials/publish-conda-forge.md:15 +#: ../../tutorials/publish-pypi.md:13 +#: ../../tutorials/pyproject-toml.md:19 +#: ../../tutorials/setup-py-to-pyproject-toml.md:12 +msgid "Learning Objectives" +msgstr "" + +#: ../../tutorials/intro.md:70 +msgid "This lesson introduces you to the basic components of a Python package. After reading this lesson you will:" +msgstr "" + +#: ../../tutorials/intro.md:73 +msgid "Understand what a Python package is" +msgstr "" + +#: ../../tutorials/intro.md:74 +msgid "Be able to list the 5 core components of a Python package" +msgstr "" + +#: ../../tutorials/intro.md:75 +msgid "Be able to explain the difference between generalizable code and code that supports a specific scientific application" +msgstr "" + +#: ../../tutorials/intro.md:82 +msgid "At a high level, you can think about a Python package as a toolbox that you can use to perform various tasks." +msgstr "" + +#: ../../tutorials/intro.md:85 +msgid "A Python package is basically a directory with a specific file structure. Within the package directory structure, there are modules which are files that end in `.py` (the same extension you'd see in a Python script). These modules allow you to group and structure your Python code. Each module contains functions and classes, that you can think about as the tools in your toolbox." +msgstr "" + +#: ../../tutorials/intro.md:94 +msgid "Diagram showing a sketch of a toolbox filled with different tools including a hammer and a saw." +msgstr "" + +#: ../../tutorials/intro.md:96 +msgid "You can think about a package as a toolbox filled with coding tools. A tool may be a function or a class. Each tool does a specific thing well." +msgstr "" + +#: ../../tutorials/intro.md:101 +msgid "Python packages are installable" +msgstr "" + +#: ../../tutorials/intro.md:103 +msgid "A package is installable, which means that you can add the functionality within the package's code to any Python environment and import that functionality like you would import core scientific Python packages such as NumPy or Matplotlib." +msgstr "" + +#: ../../tutorials/intro.md:112 +msgid "Installing a package into an environment makes it easier to manage and reuse your code across different projects. Structuring your code as a package is the first step you need to take so you can share the tools in the toolbox you've created and let others build with it." +msgstr "" + +#: ../../tutorials/intro.md:117 +msgid "Why create a Python package?" +msgstr "" + +#: ../../tutorials/intro.md:119 +msgid "You might create a Python package because you want to:" +msgstr "" + +#: ../../tutorials/intro.md:121 +msgid "**Use your code across different projects:** At its most basic level, creating a package allows you to install your code into a Python environment. This allows you to then import functions and classes into any workflows both locally and in the cloud." +msgstr "" + +#: ../../tutorials/intro.md:122 +msgid "**Share your code:** If you publish a package on a public repository such as PyPI or conda, your package can be installed on any machine using pip or conda with a single command." +msgstr "" + +#: ../../tutorials/intro.md:123 +msgid "**Build community around your code:** Packages make it easier for multiple people to work on the same project (particularly when published on GitHub). A version control system such as git (the system used by GitHub), further makes it easier to track changes to the codebase over time. Tools such as issues and pull requests make it easier for outside users to contribute bug fixes and to establish review processes for accepting changes to the code base." +msgstr "" + +#: ../../tutorials/intro.md:124 +msgid "**Organize your code:** Packages can be used to organize large code projects, dividing them into smaller, more manageable components. This structure can help with both maintaining the codebase and with making it easier to understand." +msgstr "" + +#: ../../tutorials/intro.md:126 +msgid "What to consider before you create a package" +msgstr "" + +#: ../../tutorials/intro.md:128 +msgid "Creating a Python package that others use takes considerable time and effort. Before you begin, think about your goals including:" +msgstr "" + +#: ../../tutorials/intro.md:131 +msgid "Who you think will use your package" +msgstr "" + +#: ../../tutorials/intro.md:132 +msgid "How people might use your package and on what data (if data are relevant)" +msgstr "" + +#: ../../tutorials/intro.md:133 +msgid "Whether you have time to add things such as documentation and tests" +msgstr "" + +#: ../../tutorials/intro.md:134 +msgid "How long you might be able to maintain it: remember that once people begin using your package they will depend on your maintainer team to update it, fix bugs and answer questions." +msgstr "" + +#: ../../tutorials/intro.md:136 +msgid "Before creating a user-facing package, it's important to consider all of the above." +msgstr "" + +#: ../../tutorials/intro.md:138 +msgid "The elements of a Python package" +msgstr "" + +#: ../../tutorials/intro.md:142 +#: ../../tutorials/intro.md:220 +msgid "Diagram showing .. more here if this stays." +msgstr "" + +#: ../../tutorials/intro.md:144 +msgid "The elements of a Python package include code, documentation, tests, an OSI-approved license and infrastructure. Maintainers are at the core making sure everything works and is up to date while fixing bugs and addressing user concerns." +msgstr "" + +#: ../../tutorials/intro.md:150 +msgid "The core elements of Python package include:" +msgstr "" + +#: ../../tutorials/intro.md:152 +msgid "**Code:** Functions and classes that provide functionality for a user of your package" +msgstr "" + +#: ../../tutorials/intro.md:153 +msgid "**Documentation:** Installation instructions, tutorials, and examples that both help users get started using your package and contributors and maintainers fix bugs and maintain the package." +msgstr "" + +#: ../../tutorials/intro.md:154 +msgid "Contributor Documentation in the form of a **CONTRIBUTING.md** file is useful to help people to contribute to your package." +msgstr "" + +#: ../../tutorials/intro.md:155 +msgid "Development Documentation helps both maintainers and contributors understand how to maintain a package's infrastructure." +msgstr "" + +#: ../../tutorials/intro.md:156 +msgid "**Tests:** that make sure your code works as it should and makes it easier for you and others to contribute to, modify and update the code in the future" +msgstr "" + +#: ../../tutorials/intro.md:157 +msgid "**License:** An open source license, or license that is [OSI approved](https://opensource.org/licenses/), refers to an license that allows others to use your package. It also provides legal direction regarding how elements of the package can and can't be reused." +msgstr "" + +#: ../../tutorials/intro.md:158 +msgid "**Infrastructure** that automates updates, publication workflows and runs test suites. Infrastructure includes a suite of things such as platforms like GitHub and GitLab, tools to run tests and tools locally such as nox and tox and continuous integration that automates package maintenance steps." +msgstr "" + +#: ../../tutorials/intro.md:160 +msgid "What pyOpenSci looks for in a package" +msgstr "" + +#: ../../tutorials/intro.md:163 +msgid "pyOpenSci performs an [initial set of editor checks](https://www.pyopensci.org/software-peer-review/how-to/editor-in-chief-guide.html#editor-checklist-template) for any package submitted to us for peer review. You may find these checks useful as you create your package as a baseline for things that you package should have." +msgstr "" + +#: ../../tutorials/intro.md:169 +msgid "Packages are more than just code - Infrastructure" +msgstr "" + +#: ../../tutorials/intro.md:171 +msgid "A package in any language is more than just code. If you expect other people to use your package, besides yourself, you should consider not only writing high quality code, but also the various elements of a package that make it a useful community resource." +msgstr "" + +#: ../../tutorials/intro.md:176 +msgid "Version control and storing your package on GitHub or GitLab" +msgstr "" + +#: ../../tutorials/intro.md:178 +msgid "Most Python packages live in an online version control platform such as GitHub or GitLab. GitHub and GitLab both run [git](https://git-scm.com/) for version control. Having your software under version control is important because it allows you to both track changes over time while also going back in history and undoing changes in the case that a change to the code base unexpectedly breaks something." +msgstr "" + +#: ../../tutorials/intro.md:183 +msgid "By publishing your package on GitHub or GitLab, you are making your code public facing. This means that others can both see your code and also make contributions using a pull request (GitHub) / merge request (GitLab) / code review workflow." +msgstr "" + +#: ../../tutorials/intro.md:185 +msgid "GitHub & GitLab vs. Git" +msgstr "" + +#: ../../tutorials/intro.md:188 +msgid "GitHub and GitLab are online (cloud) platforms that run `git` (version control software) on the backend. Running git locally on your computer allows you to upload (`git push`) and download (`git pull`) files to GitHub and GitLab." +msgstr "" + +#: ../../tutorials/intro.md:193 +msgid "Issues or Ticket Trackers" +msgstr "" + +#: ../../tutorials/intro.md:195 +msgid "GitHub and GitLab also both offer community features such as issues that allow:" +msgstr "" + +#: ../../tutorials/intro.md:197 +msgid "you to communicate with your maintainers and contributor community" +msgstr "" + +#: ../../tutorials/intro.md:198 +msgid "users to report bugs, ask questions and request new features" +msgstr "" + +#: ../../tutorials/intro.md:199 +msgid "you to publicly keep track of enhancements and features you want to work on for your package." +msgstr "" + +#: ../../tutorials/intro.md:201 +msgid "Continuous integration and continuous deployment" +msgstr "" + +#: ../../tutorials/intro.md:203 +msgid "GitHub and GitLab also provide continuous integration and continuous deployment (CI/CD). Continuous integration (CI) refers to a platform that automatically runs a specific job when a certain event occurs, whereas continuous deployment (CD) is an extension of CI that refers to not only running or building but also to publishing the final outputs somewhere." +msgstr "" + +#: ../../tutorials/intro.md:205 +msgid "**An example of Continuous integration:**" +msgstr "" + +#: ../../tutorials/intro.md:207 +msgid "When someone submits a change to your code, your tests will run across different operating systems and the code will be checked for format issues." +msgstr "" + +#: ../../tutorials/intro.md:209 +msgid "**An example of Continuous deployment:**" +msgstr "" + +#: ../../tutorials/intro.md:211 +msgid "When you are ready to release your package to PyPI, a continuous deployment operation might be triggered on release to publish your package to PyPI." +msgstr "" + +#: ../../tutorials/intro.md:213 +msgid "Integrated CI/CD will help you maintain your software, ensuring that changes to the code don't break things unexpectedly. They can also help you maintain code style and format consistency for every new change to your code." +msgstr "" + +#: ../../tutorials/intro.md:222 +msgid "The lifecycle of a scientific Python package." +msgstr "" + +#: ../../tutorials/intro.md:225 +msgid "When should you turn your code into a Python package?" +msgstr "" + +#: ../../tutorials/intro.md:227 +msgid "You may be wondering, what types of code should become a Python package that is both on GitHub and published to PyPI and/or conda-forge." +msgstr "" + +#: ../../tutorials/intro.md:229 +msgid "There are a few use cases to consider:" +msgstr "" + +#: ../../tutorials/intro.md:231 +msgid "**Creating a basic package for yourself:** Sometimes you want create a package for your own personal use. This might mean making your code locally pip installable and you may also want to publish it to GitHub. In that case you don't expect others to use your code, and as such you may only have documentation for you and your future self if you need to update the package." +msgstr "" + +#: ../../tutorials/intro.md:233 +msgid "An example of this type of package might be a set of functions that you write that are useful across several of your projects. It could be useful to have those functions available to all of your projects." +msgstr "" + +#: ../../tutorials/intro.md:236 +msgid "LINK to pip installable lesson when it's published - it's in review now" +msgstr "" + +#: ../../tutorials/intro.md:239 +msgid "**Creating a package for the community:** In other cases, you may create some code that you soon realize might also be useful to not just you, but to other people as well. In that case, you might consider both creating the package, publishing it on GitHub, and because other users may be using it, you may make use of GitHub's infrastructure including CI/CD pipelines and issue trackers. Because you want other people to use your package, you will want to also include LICENSE information, documentation for users and contributors and tests. This type of package is most often published to PyPI." +msgstr "" + +#: ../../tutorials/intro.md:242 +msgid "For example, all of the [pyOpenSci packages](https://www.pyopensci.org/python-packages.html) are public facing with an intended audience beyond just the maintainers." +msgstr "" + +#: ../../tutorials/intro.md:244 +msgid "Packages that you expect others to use should be well-scoped" +msgstr "" + +#: ../../tutorials/intro.md:246 +msgid "Ideally the code in your Python package is focused on a specific theme or use case. This theme is important as it's a way to scope the content of your package." +msgstr "" + +#: ../../tutorials/intro.md:248 +msgid "It can be tricky to decide when your code becomes something that might be more broadly useful to others. But one question you can ask yourself is - is your code written specifically for a single research project? Or could it have a broader application across multiple projects in your domain?" +msgstr "" + +#: ../../tutorials/intro.md:250 +msgid "How does this relate to code for a research project?" +msgstr "" + +#: ../../tutorials/intro.md:253 +msgid "A [Research Compendium](https://the-turing-way.netlify.app/reproducible-research/compendia.html) is an organized set of code, data and documentation that supports a specific research project. It aims to enhance the reproducibility and transparency of research by providing a comprehensive record of the methods, data, and analyses used in a study." +msgstr "" + +#: ../../tutorials/intro.md:258 +msgid "A Python package is a collection of modules that can be used to perform a specific set of tasks. These tasks should be applicable to numerous workflows. As such a Python package is more generalizable than a Research Compendium which supports a specific project." +msgstr "" + +#: ../../tutorials/intro.md:263 +msgid "[Read about `Good enough practices in scientific computing`](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1005510)" +msgstr "" + +#: ../../tutorials/intro.md:264 +msgid "[Learn more about research compendia (also called repo-packs) in this blog post.](https://lorenabarba.com/blog/how-repro-packs-can-save-your-future-self/)" +msgstr "" + +#: ../../tutorials/intro.md:267 +msgid "Below are a few examples well scoped pyOpenSci packages:" +msgstr "" + +#: ../../tutorials/intro.md:269 +msgid "[Crowsetta](https://crowsetta.readthedocs.io/en/latest/): is a package designed to work with annotating animal vocalizations and bioacoustics data. This package helps scientists process different types of bioacoustic data rather than focusing on a specific individual research application associated with a user-specific research workflow." +msgstr "" + +#: ../../tutorials/intro.md:270 +msgid "[Pandera](https://www.union.ai/pandera) is another more broadly used Python package. Pandera supports data testing and thus also has a broader research application." +msgstr "" + +#: ../../tutorials/intro.md:272 +msgid "Matplotlib as an example" +msgstr "" + +#: ../../tutorials/intro.md:274 +msgid "At the larger end of the user spectrum, Matplotlib is a great example. Matplotlib does one thing really well:" +msgstr "" + +#: ../../tutorials/intro.md:277 +msgid "_It creates visual plots of data._" +msgstr "" + +#: ../../tutorials/intro.md:279 +msgid "Thousands of people use Matplotlib for different plotting applications using different types of data. While few scientific packages will have the same broad application and large user base that Matplotlib has, the idea of scoping out what your package does is still important." +msgstr "" + +#: ../../tutorials/intro.md:285 +msgid "Code should also be clean & readable & documented" +msgstr "" + +#: ../../tutorials/intro.md:287 +msgid "The code in your package should also be clean, readable, and well documented." +msgstr "" + +#: ../../tutorials/intro.md:289 +msgid "**Clean code:** Clean code refers to code that uses expressive variable names, is concise and doesn't repeat itself. You can learn about best practices for clean code in future pyOpenSci tutorials." +msgstr "" + +#: ../../tutorials/intro.md:293 +msgid "**Readable code:** readable code is code written with a consistent style. You can use linters and code formatters such as black and flake8 to ensure this consistency throughout your entire package. [Learn more about code formatters here.](../package-structure-code/code-style-linting-format)" +msgstr "" + +#: ../../tutorials/intro.md:297 +msgid "**Documented code:** documented code is written using docstrings that help a user understand both what the functions and methods in your code do and also what the input and output elements of each function are. [You can learn more about docstrings in our guide, here.](../documentation/write-user-documentation/document-your-code-api-docstrings)" +msgstr "" + +#: ../../tutorials/intro.md:301 +msgid "Making your package installable - publishing to PyPI & conda-forge" +msgstr "" + +#: ../../tutorials/intro.md:303 +msgid "Python packages and environments" +msgstr "" + +#: ../../tutorials/intro.md:305 +msgid "You can install a Python package into a Python environment in the same way you might install NumPy or Pandas. Installing your package into an environment allows you to access it from any code run with that specific Python environment activated." +msgstr "" + +#: ../../tutorials/intro.md:311 +msgid "Diagram showing the steps associated with creating a package and then installing it. The first arrow says your package and the second says pip install package. The second arrow leads to a box that represents a Python environment that already has some packages installed such as Pandas and NumPy. Your package will also get installed into that same environment when you pip install it." +msgstr "" + +#: ../../tutorials/intro.md:313 +msgid "You don't have to publish to PyPI to make your code installable. With the correct file structure and project metadata you can make your code installable locally on your computer and use it for projects that you are working on without having to ever publish to PyPI. Publishing to PyPI is useful when you want to make your code public-facing and share it with others." +msgstr "" + +#: ../../tutorials/intro.md:320 +msgid "Publishing a package to PyPI / Conda-Forge" +msgstr "" + +#: ../../tutorials/intro.md:322 +msgid "If you want to make your package directly installable without having to download the code to your computer locally then you need to publish it in a repository such as **PyPI** or **conda-forge**." +msgstr "" + +#: ../../tutorials/intro.md:326 +msgid "Learn [how to publish your package to PyPI in this tutorial.](publish-pypi.md)" +msgstr "" + +#: ../../tutorials/intro.md:328 +msgid "Then you can create a conda-forge recipe using the [Grayskull](https://github.com/conda/grayskull) tool. You can then submit this recipe to conda-forge." +msgstr "" + +#: ../../tutorials/intro.md:330 +msgid "[You will learn more about the conda-forge publication process here.](publish-conda-forge.md)" +msgstr "" + +#: ../../tutorials/intro.md:333 +msgid "Graphic showing the high level packaging workflow. On the left you see a graphic with code, metadata and tests in it. Those items all go into your package. Documentation and data are below that box because they aren't normally published in your packaging wheel distribution. An arrow to the right takes you to a build distribution files box. That box leads you to either publishing to TestPyPI or the real PyPI. From PyPI you can then connect to conda-forge for an automated build that sends distributions from PyPI to conda-forge." +msgstr "" + +#: ../../tutorials/intro.md:335 +msgid "In the image above, you can see the steps associated with publishing your package on PyPI and conda-forge. Note that the distribution files that PyPI requires are the [sdist](#python-source-distribution) and [wheel](#python-wheel) files. Once you are ready to make your code publicly installable, you can publish it on PyPI. Once your code is on PyPI it is straight forward to then publish to conda-forge. You create a recipe using the Grayskull package and then you open a pr in the conda-forge recipe repository. You will learn more about this process in the [conda-forge lesson](/tutorials/publish-conda-forge)." +msgstr "" + +#: ../../tutorials/intro.md:339 +msgid "Yay, your package has users! Now what?" +msgstr "" + +#: ../../tutorials/intro.md:341 +msgid "As the community using your package grows, you may also find yourself managing users, contributors, and others who want to interact with your package. It’s important to consider all this before you dive into development. Once you have a user base in the community, people will depend upon your code to work and will need direction regarding how to use it." +msgstr "" + +#: ../../tutorials/intro.md:343 +msgid "To support your community, you'll want to add things like:" +msgstr "" + +#: ../../tutorials/intro.md:345 +msgid "[a development guide that documents your maintainer workflow process ](/documentation/repository-files/development-guide.md)" +msgstr "" + +#: ../../tutorials/intro.md:346 +msgid "[a code of conduct to defines community interaction standards and expectations](/documentation/repository-files/code-of-conduct-file.md)" +msgstr "" + +#: ../../tutorials/intro.md:347 +msgid "[a contributing guide that helps users understand expectations associated with making contributions to your project](/documentation/repository-files/contributing-file.md)" +msgstr "" + +#: ../../tutorials/intro.md:349 +msgid "Support for contributors and maintainers" +msgstr "" + +#: ../../tutorials/intro.md:351 +msgid "If you intend for others to use and contribute to your code, consider who will maintain it over time. You will want a **contributing and development** guide to help new potential contributors get started with contributing to your package, as well as a **code of conduct** to ensure community interactions remain healthy both for you and your contributors and maintainer team." +msgstr "" + +#: ../../tutorials/intro.md:353 +msgid "The elements above are also important for future maintenance of your package. In the case that you are no long able to maintain it or simply want extra help, development, and contributing documentation will help you onboard new maintainers." +msgstr "" + +#: ../../tutorials/intro.md:358 +msgid "What's next?" +msgstr "" + +#: ../../tutorials/intro.md:360 +msgid "In future lessons you will learn more about the infrastructure around a published Python package that makes it both easier to maintain, easier for others to contribute to and easier for other scientists to use. However, first we want to get you to your initial goal of publishing a Python package." +msgstr "" + +#: ../../tutorials/intro.md:362 +msgid "In this next lesson you will learn how to create a basic installable Python package. Make your code pip installable " +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:1 +msgid "Publish your Python package that is on PyPI to conda-forge" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:3 +msgid "In the previous lessons, you've learned:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:5 +msgid "How to [create the most basic version of a Python package](installable-code.md). This entailed making your code installable." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:6 +msgid "[How to publish your Python package to PyPI](publish-pypi)" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:7 +msgid "How to add a `README` and `LICENSE` file to your package" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:8 +msgid "How to setup your `pyproject.toml` file with all of the metadata that PyPI requires and also metadata that will be helpful for users to find your package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:10 +msgid "If you have gone through all of the above lessons, you are now ready to publish your package on conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:13 +msgid "**IMPORTANT:** Please do not practice publishing your package to conda-forge. You should only publish to conda-forge when you have a package on pypi.org that you plan to maintain." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:19 +#: ../../tutorials/publish-pypi.md:17 +msgid "In this lesson you will learn how to:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:21 +msgid "Create a conda-forge yaml recipe for your package using Grayskull" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:22 +msgid "Submit the recipe (yaml file) to the conda-forge staged recipes repository as a pull request" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:23 +msgid "Maintain your conda-forge package by creating new releases for your package on PyPI" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:26 +msgid "Once your package is on PyPI you can then easily publish it to conda-forge using the [grayskull](https://conda.github.io/grayskull/) tool. You do not need to build the package specifically for conda, conda-forge will build from your PyPI source distribution file (sdist)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:33 +msgid "Image showing the progression of creating a Python package, building it and then publishing to PyPI and conda-forge. You take your code and turn it into distribution files (sdist and wheel) that PyPI accepts. Then there is an arrow towards the PyPI repository where ou publish both distributions. From PyPI if you create a conda-forge recipe you can then publish to conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:35 +msgid "Once you have published both package distributions (the source distribution and the wheel) to PyPI, you can then publish to conda-forge. Conda-forge requires a source distribution on PyPI in order to build your package on conda-forge. You do not need to rebuild your package to publish to conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:38 +msgid "What is conda-forge?" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:40 +msgid "conda is an open source package and environment management tool that can be used to install tools from the different channels on Anaconda.org." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:43 +msgid "You can think about a channel as a specific location where a group of packages are stored and can be installed from using a command such as `conda install packagename`. In the case of conda channels, some of these channels such as the `defaults` channel, is managed by Anaconda (the company). Only Anaconda can decide what packages are available in the `defaults` channel. However, the conda-forge (and bioconda) channel are community-managed channels. Anyone can submit a package to these channels however they must pass a technical review in the [staged-recipes GitHub repository](https://github.com/conda-forge/staged-recipes) to be published." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:46 +msgid "[Learn more about conda channels here.](#about-conda)" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:50 +msgid "Graphic with the title Python package repositories. Below it says anything hosted on PyPI can be installed using pip install. Packaging hosted on a conda channel can be installed using conda install. Below that there are two rows. The top row says conda channels. Next to it are three boxes one with conda-forge, community maintained; bioconda and then default - managed by the Anaconda team. Below that there is a row that says PyPI servers. PyPI - anyone can publish to PyPI and test PyPI (a testbed server for you to practice)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:52 +msgid "Conda channels represent various repositories that you can install packages from. Because conda-forge is community maintained, anyone can submit a recipe there. PyPI is also a community maintained repository. Anyone can submit a package to PyPI and test PyPI. Unlike conda-forge there are no manual checks of packages submitted to PyPI." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:55 +msgid "Why publish to conda-forge" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:57 +msgid "There are many users, especially in the scientific Python ecosystem that use conda as their primary package manager / environment tool. Thus, having packages available to these users on the conda-forge channel is useful. In some cases packages on conda-forge can minimize dependency conflicts that can occur when mixing installations using pip and conda. This is particularly important for the spatial ecosystem." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:59 +msgid "How publishing to conda-forge works" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:61 +msgid "Once you have built and published your package to PyPI, you have everything that you need to publish to conda-forge. There is no additional build step needed to publish to conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:63 +msgid "Conda-forge will build your package from the source distribution which you [published to PyPI in the previous lesson](publish-pypi) using the recipe that you will create below." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:65 +msgid "Conda-forge publication steps" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:68 +msgid "Image showing the steps associated with publishing to conda-forge. Check out the caption below for a detailed description." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:70 +msgid "The steps for publishing to conda-forge begin with publishing your Python package to PyPI. Once you have published to PyPI you can then create a yaml file recipe that can be submitted to the conda-forge staged recipes repository for review. Once that recipe is accepted, your package will get it's on repository (known as a feedstock) on conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:73 +msgid "The steps to publish to conda-forge are:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:75 +msgid "Publish your Python package distribution files (sdist & wheel) to PyPI" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:76 +msgid "Create a conda-forge recipe, which is a yaml file with instructions on how to build your package on conda-forge, using the grayskull[^grayskull] package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:77 +msgid "Submit the recipe (yaml file) to the conda-forge staged recipes repository as a pull request for review. [Click here for an example submission from pyOpenSci.](https://github.com/conda-forge/staged-recipes/pull/25173)" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:79 +msgid "Once someone from the conda-forge team reviews your pull request, you may need to make some changes. Eventually the pull request will be approved and merged." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:81 +msgid "Once your recipe is accepted and merged on conda-forge, users can install your package using:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:83 +msgid "`conda install -c conda-forge your-package`" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:85 +msgid "You only create the recipe once. Once the recipe is accepted and merged, you only need to maintain the repository." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:87 +msgid "Maintaining a conda-forge package" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:89 +msgid "Once your package is on conda-forge, the repository will track release activity on the package's PyPI repository. Any time you make a new PyPI release with a new source distribution, conda-forge will build and update your conda-forge repository (also known as a feedstock)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:91 +msgid "When the update is processed, the friendly conda-forge bot will create a new pull request with an updated distribution recipe in your feedstock." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:93 +msgid "You can review that pull request and then merge it once all of the continuous integration tests pass." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:95 +msgid " How to Publish your package on conda-forge" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:97 +msgid "It's time to add your package to the conda-forge channel. Remember that your package needs to be on PyPI before the steps below will work. And also remember that the team managing conda-forge are all volunteers." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:100 +msgid "Be sure that your package is on PyPI.org (not test.pypi.org) before you attempt to publish to conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:103 +msgid "Only submit your package to conda-forge if you intend to maintain it over time." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:106 +msgid "Note - this is a tutorial aimed to help you get your package onto conda-forge. The official conda documentation for this processed [is here](https://conda-forge.org/docs/maintainer/adding_pkgs.html)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:108 +msgid "Step 1: Install grayskull" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:110 +msgid "First, [install grayskull](https://conda.github.io/grayskull/user_guide.html). You can install it using either pip:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:116 +msgid "or conda" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:122 +msgid "To run this command, use the same shell / terminal that you have been using to run hatch commands in the previous tutorials." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:127 +msgid "You can also install grayskull using pipx[^pipx]. pipx is a tool that allows you to install commonly used tools that you might want to have available across multiple Python environments rather than installing the package into every Python environment that you create." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:130 +msgid "Step 2: Fork and clone the conda-forge staged-recipes repository" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:132 +msgid "Next, open your shell and `cd` to a location where you want to clone the **conda-forge/staged-recipes** repository." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:133 +msgid "fork and clone the [conda-forge/staged-recipes GitHub repository](https://github.com/conda-forge/staged-recipes)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:134 +msgid "Create a new branch in your fork rather than submitting from the main branch of your fork. We suggest naming the branch your package's name." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:136 +msgid "`git checkout -b your-package-name `" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:138 +msgid "In bash, `cd` into the `staged-recipes/recipes` folder" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:146 +msgid "Next, create a new branch in your `conda-forge/staged-recipes` cloned repository. You might want to make that branch the same name as your package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:157 +msgid "Step 3: Create your conda-forge recipe" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:159 +msgid "Next, navigate to the recipes directory" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:161 +msgid "If you run `ls` here, you will notice there is an example directory with an example recipe for you to look at." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:173 +msgid "Next, run `grayskull pypi your-package-name` to generate a recipe." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:217 +msgid "Grayskull will pull metadata about your package from PyPI. It does not use your local installation of the package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:218 +msgid "An internet connection is needed to run the `grayskull pypi your-package-name` step." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:221 +msgid "When you run grayskull, it will grab the latest distribution of your package from PyPI and will use that to create a new recipe." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:223 +msgid "The recipe will be saved in a directory named after your package's name, wherever you run the command." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:225 +msgid "`recipes/packagename/meta.yaml`" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:227 +msgid "At the very bottom of the grayskull output, it will also tell you where it saved the recipe file." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:230 +msgid "Open the meta.yaml file. The finished `meta.yaml` file that grayskull creates should look like the example below:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:277 +msgid "Step 3b: Bug fix - add a home url to the about: section" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:279 +msgid "There is currently a small bug in Grayskull where it doesn't populate the home: element of the recipe. If you don't include this, [you will receive an error message](https://github.com/conda-forge/staged-recipes/pull/25173#issuecomment-1917916528) from the friendly conda-forge linter bot." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:293 +msgid "to fix this, open your meta.yaml file in your favorite text editor." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:294 +msgid "and add a home: element to the about section" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:296 +msgid "The about section will look like this after you create your recipe." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:306 +msgid "Below you add a home: element. If you have a project home page / website you can use that url. Otherwise, you can also use your PyPI landing page." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:317 +msgid "Step 4: tests for conda-forge" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:319 +msgid "Next, have a look at the tests section in your **meta.yaml** file. At a minimum you should import your package or the main modules associated with your package and run `pip check`." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:321 +msgid "`pip check` will ensure that your package installs properly with all of the proper dependencies." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:333 +msgid "If you have more advanced tests that you wish to run, you can add them here. However, you can also simply leave the tests section as it is." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:335 +msgid "Step 4: Submit a pull request to the staged-recipes repository" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:337 +msgid "Once you have completed all of the above, you are ready to open up a pull request in the `conda-forge/staged-recipes repository`." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:339 +msgid "Submit a pull request from your fork/branch of the staged-recipes repository." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:340 +msgid "Remember that the conda-forge maintainers are volunteers. Be patient for someone to respond and supportive in your communication with them." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:0 +msgid "Conda-forge checklist help" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:346 +msgid "Conda-forge Staged-recipes Pull Request Checklist" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:348 +msgid "When you submit your package to conda-forge, the pull request template includes a list of checks that you want to ensure you have covered." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:350 +msgid "Below we break down each element of that list." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:352 +msgid "Pull request template checklist tips" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:355 +msgid "-[x] Title of this PR is meaningful: e.g. \"Adding my_nifty_package\", not \"updated meta.yaml\"." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:357 +msgid "**Translation:** Make sure that your pull request title is specific. We suggest something like: `Add recipe for `" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:360 +msgid "-[x] License file is packaged (see [here](https://github.com/conda-forge/staged-recipes/blob/5eddbd7fc9d1502169089da06c3688d9759be978/recipes/example/meta.yaml#L64-L73) for an example)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:362 +msgid "**Translation:** You should have a LICENSE file included in your package's source distribution. If you have followed the pyOpenSci tutorials then you already have a LICENSE file and are likely using the MIT license. When you run `hatch build`, it will bundle that file into the output [source distribution file (which is the tar.gz file)](python-source-distribution) that conda-forge will use to build your package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:364 +msgid "[x] Source is from official source." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:366 +msgid "**Translation:** If your package is on PyPI as you learned in the [previous lesson on publishing your Python package](publish-pypi) then you are in good shape. conda-forge prefers that your distribution is published to a known repository." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:368 +msgid "-[x] Package does not vendor other packages. (If a package uses the source of another package, they should be separate packages or the licenses of all packages need to be packaged)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:370 +msgid "**Translation:** If the code base in your package is your own and it all shares the same LICENSE then you are in good shape. If you have code taken from other packages then you may need to declare that and include licenses for that code if it is different. If you followed these tutorials then you do not have any vendored code." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:372 +msgid "-[x] If static libraries are linked in, the license of the static library is packaged." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:374 +msgid "-[x] Package does not ship static libraries. If static libraries are needed, [follow CFEP-18](https://github.com/conda-forge/cfep/blob/main/cfep-18.md)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:376 +msgid "**Translation:** A static library refers to a copy of a package built into your package. If your package is a pure Python package, then you can check that your package does not ship static libraries as this does not apply to you." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:378 +msgid "The pyOpenSci tutorials are all pure Python and as such do not use static libraries in a linked or shipped (included in the package distribution) format." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:380 +msgid "If your package has a more complex build that includes links to extensions written in other languages such as C++, then be sure to include the proper licenses for those extensions in your metadata." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:385 +msgid "If you want to learn more about static libraries, then [this overview](https://pypackaging-native.github.io/background/compilation_concepts/#shared-vs-static-libraries) might help." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:388 +msgid "-[ ] Build number is 0." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:390 +msgid "**Translation:** The build number in your recipe is right below the source location of your package's source distribution. `number: 0` is what you should see in that section of your recipe." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:403 +msgid "[x] A tarball (`url`) rather than a repo (e.g. `git_url`) is used in your recipe (see [here](https://conda-forge.org/docs/maintainer/adding_pkgs.html) for more details)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:405 +msgid "**Translation:** Here conda wants you to provide a link to the source distribution on PyPI rather than a link to your GitHub repository distribution. Notice above in the Source section of your recipe there is a `url:` section that provides a PyPI url that ends in tar.gz. That is a link to your source distribution that conda-forge will use." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:411 +msgid "[x] GitHub users listed in the maintainer section have posted a comment confirming they are willing to be listed there." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:413 +msgid "**Translation** Once you have submitted your recipe, be sure that all maintainers listed in your recipe respond acknowledging that they are ok with being listed as a maintainer for the conda-forge version of your package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:415 +msgid "[x] When in trouble, please check our [knowledge base documentation](https://conda-forge.org/docs/maintainer/knowledge_base.html) before pinging a team." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:417 +msgid "**Translation** The conda team are volunteers who spend their time supporting our community. Please try to troubleshoot on your own first before tagging one of them for help." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:419 +msgid "This is also why we don't suggest you publish to conda-forge as a practice run." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:423 +msgid "Once you create your pull request, a suite of CI actions will run that build and test the build of your package. A conda-forge maintainer will work with you to get your recipe in good shape and merged." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:427 +msgid "Image showing the 5 CI tasks that will run against your package in the GitHub interface after you'ce created a pull request." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:429 +msgid "Wait until all of the CI steps in your pull request have run. At that point your pull request is ready for review by a conda-forge maintainer." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:432 +msgid "In some cases getting all of the checks to run successfully in CI might take a bit of work. If you are struggling to get your recipe to build properly, you can ping the conda-forge maintainer team for help." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:434 +msgid "Please be patient and wait for them to respond." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:436 +msgid "conda-forge staged recipes and CI failures" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:439 +msgid "If your package is a pure Python package that can be installed on any type of computer (Windows, mac, linux) and has no architecture requirements (known as noarch: Python or no architecture requirements) then the conda-forge team only requires tests for Linux CI to pass." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:441 +msgid "So if tests for Windows and MAC OS fail, that is to be expected. In this case, don't worry about failing tests, the maintainer team can help you get your package published." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:444 +msgid "Once you have submitted your recipe, you can wait for the CI build to pass. If it's not passing, and you aren't sure why, a conda-forge maintainer can likely help you figure things out." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:446 +msgid "Once your recipe is built and merged, the conda team will create a new package repository for you similar to [this one for the GemGIS package](https://github.com/conda-forge/gemgis-feedstock)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:448 +msgid " Congratulations - you have added your package to conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:450 +msgid "The last part of this process is maintaining the repository. We cover that next." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:453 +msgid "Maintaining your conda-forge feedstock" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:455 +msgid "Every time you create a new release on PyPI, the conda-forge bots will recognize the release and will rebuild the newly released version of your package. This process may take a day or two to complete so be patient." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:457 +msgid "Once the conda-forge build is complete, all of the maintainers of your conda-forge feedstock will get a ping on GitHub that a new pull request has been opened." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:459 +msgid "Review the pull request. If all tests are passing, you can merge it. Shortly after merging your pull request, the conda-forge release will be available for users to install:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:461 +msgid "`conda install -c conda-forge yourpackage`" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:465 +msgid "If you have walked through this entire tutorial series you will now:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:467 +msgid "Understand [what a Python package is ](intro.md)" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:468 +msgid "Know how to [make your code installable](installable-code.md) into Python environments" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:469 +msgid "Know how to create a `pyproject.toml` file, a `README` file, and a `LICENSE` and code of conduct." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:470 +msgid "Know how to [publish your package to PyPI](publish-pypi.md) and" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:471 +msgid "Know how to publish your package to conda-forge" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:473 +msgid "The above are the basic steps that you need to take to create and publish a Python package. In a future tutorial series we will cover that basics of maintaining your package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:477 +msgid "[Grayskull blogpost](https://conda-forge.org/blog/2020/03/05/grayskull/)" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:478 +msgid "[Pipx documentation](https://pipx.pypa.io/stable/)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:1 +msgid "Publish your Python package to PyPI" +msgstr "" + +#: ../../tutorials/publish-pypi.md:4 +msgid "Make sure they add /dist to their .gitignore file. We have not discussed GitHub workflows anywhere yet. Where does that fit?" +msgstr "" + +#: ../../tutorials/publish-pypi.md:8 +msgid "In the previous Python packaging lessons, you've learned:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:10 +msgid "What a Python package is" +msgstr "" + +#: ../../tutorials/publish-pypi.md:11 +msgid "How to make your code installable." +msgstr "" + +#: ../../tutorials/publish-pypi.md:19 +msgid "Build your package's source (sdist) and wheel distributions" +msgstr "" + +#: ../../tutorials/publish-pypi.md:20 +msgid "Setup an account on TestPyPI (the process is similar for PyPI)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:21 +msgid "Publish your package to TestPyPI and PyPI" +msgstr "" + +#: ../../tutorials/publish-pypi.md:23 +msgid "You will do all of your development work in this lesson using [Hatch](https://hatch.pypa.io/latest/)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:25 +msgid "Once your package is on PyPI you can publish it to conda-forge (which is a channel on conda) using [Grayskull](https://conda.github.io/grayskull/)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:28 +msgid "You will learn how to publish to conda-forge in the [next lesson](publish-conda-forge)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:32 +msgid "Graphic showing the high level packaging workflow. On the left you see a graphic with code, metadata and tests in it. Those items all go into your package. An arrow to the right takes you to a build distribution files box. Another arrow to the right takes you to a publish to PyPI box which has an arrow containing sdist and wheel that notes those files go to PyPI for hosting. From PyPI is an arrow containing sdist since you can then connect to conda-forge for an automated build that sends distributions from PyPI to conda-forge." +msgstr "" + +#: ../../tutorials/publish-pypi.md:34 +msgid "You need to build your Python package in order to publish it to PyPI (or Conda). The build process organizes your code and metadata into a distribution format that can be uploaded to PyPI and subsequently downloaded and installed by users." +msgstr "" + +#: ../../tutorials/publish-pypi.md:37 +msgid "TestPyPI vs PyPI" +msgstr "" + +#: ../../tutorials/publish-pypi.md:39 +msgid "There are two repositories associated with PyPI to which you can upload your Python package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:42 +msgid "**[TestPyPI](https://test.pypi.org):** TestPyPI is a package repository provided by PyPI that you can use for testing that your package can be uploaded, downloaded, and installed correctly. This is a great place to practice and learn how to publish a package without exposing your incomplete package on the real PyPI service." +msgstr "" + +#: ../../tutorials/publish-pypi.md:43 +msgid "**[PyPI](https://pypi.org):** This is the live, production PyPI repository where you can officially publish your Python package, and from which users will get your package. IMPORTANT: Only publish your package to PyPI when you are ready for it to be used by others and/or confident that it will become a package that you will maintain. PyPI is not a place to practice learning how to publish a Python package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:45 +msgid "The steps for publishing on TestPyPI vs. PyPI are similar with the exception of a different url. We will point out where they differ." +msgstr "" + +#: ../../tutorials/publish-pypi.md:48 +msgid "4 Steps for publishing a Python package on TestPyPI (or PyPI)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:50 +msgid "In this lesson you will learn how to publish your package to TestPyPI using [Hatch](https://hatch.pypa.io/latest/). There are 4 things that you need to do to publish your Python package: to TestPyPI. You need to:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:55 +msgid "**Create a package development environment**" +msgstr "" + +#: ../../tutorials/publish-pypi.md:56 +msgid "[**Build your package using `hatch build`**](../package-structure-code/python-package-distribution-files-sdist-wheel). Building a package is the process of turning your code into two types of distribution files: sdist and wheel. The wheel distribution file is particularly important for users who will `pip install` your package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:57 +msgid "**Create an account on TestPyPI (or PyPI)**: You will need to create a TestPyPI account and associated token which provides permissions for you to upload your package. When you later publish your package to PyPI, you will need a separate PyPI account and token." +msgstr "" + +#: ../../tutorials/publish-pypi.md:58 +msgid "**Publish to TestPyPI using `hatch publish`**" +msgstr "" + +#: ../../tutorials/publish-pypi.md:60 +msgid "In a future lesson, you will learn how to create an automated GitHub Actions workflow that publishes an updated version of your package to PyPI every time you create a GitHub release." +msgstr "" + +#: ../../tutorials/publish-pypi.md:64 +msgid "Learn more about building Python packages in our guide" +msgstr "" + +#: ../../tutorials/publish-pypi.md:68 +msgid "[Learn more about what building a Python package is](../package-structure-code/python-package-distribution-files-sdist-wheel)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:69 +msgid "[Learn more about the package distribution file that PyPI needs called the wheel](#python-wheel)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:70 +msgid "[Learn more about the package distribution file that conda-forge will need on PyPI called the sdist (source distribution)](#python-source-distribution)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:73 +msgid "Step 1: Create a Python package development environment" +msgstr "" + +#: ../../tutorials/publish-pypi.md:75 +msgid "The first step in building your package is to create a development environment. The Python environment will contain all of the dependencies needed to both install and work on your package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:77 +msgid "Use Hatch to create your environment." +msgstr "" + +#: ../../tutorials/publish-pypi.md:85 +msgid "Then view all of the current environments that hatch has access to:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:97 +msgid "Then activate the environment. Note that when you call a shell from a Hatch environment, it will automatically install your package into the environment in development or editable mode." +msgstr "" + +#: ../../tutorials/publish-pypi.md:107 +msgid "View what's in the environment using `pip list`:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:123 +msgid "At any time you can exit the environment using `exit`." +msgstr "" + +#: ../../tutorials/publish-pypi.md:137 +msgid "Hatch and environments" +msgstr "" + +#: ../../tutorials/publish-pypi.md:139 +msgid "Behind the scenes when hatch creates a new virtual environment, by default it uses venv[^venv] which is the default environment management tool that comes with Python installations." +msgstr "" + +#: ../../tutorials/publish-pypi.md:142 +msgid "Hatch will:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:144 +msgid "Create a new virtualenv (venv) that is located on your computer." +msgstr "" + +#: ../../tutorials/publish-pypi.md:145 +msgid "Install your package into the environment in editable mode (similar to `python -m pip install -e`). This means it installs both your project and your project's dependencies as declared in your pyproject.toml file." +msgstr "" + +#: ../../tutorials/publish-pypi.md:147 +msgid "Step 2: Build your package's sdist and wheel distributions" +msgstr "" + +#: ../../tutorials/publish-pypi.md:149 +msgid "Once you have your development environment setup, you are ready to build your package using Hatch. Remember that building is the process of turning your Python package file structure into two distribution files:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:151 +msgid "The [wheel distribution](#python-wheel) is a pre-built version of your package. It useful for users as it can be directly installed using a tool such as `pip`. This file has the extension `.whl`." +msgstr "" + +#: ../../tutorials/publish-pypi.md:152 +msgid "The [source distribution](#python-source-distribution) contains the files that make up your package in an unbuilt format. This file will have the extension `.tar.gz`." +msgstr "" + +#: ../../tutorials/publish-pypi.md:154 +msgid "You will use Hatch as a **Front end** tool that builds your package's sdist and wheel using the [hatchling](https://hatch.pypa.io/latest/) build back-end. The hatchling build back-end is used because you declared it in your pyproject.toml file in the [previous lesson](installable-code)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:158 +msgid "To build your package run `hatch build`:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:169 +msgid "Learn more about building a Python package" +msgstr "" + +#: ../../tutorials/publish-pypi.md:171 +msgid "You can learn more about building in the [build page of our packaging guide](../package-structure-code/python-package-distribution-files-sdist-wheel)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:175 +msgid "The sdist is important if you wish to [publish your package to conda-forge](publish-conda-forge). You will learn about this in a later lesson." +msgstr "" + +#: ../../tutorials/publish-pypi.md:179 +msgid "➜ hatch build ────────────────────────────────────── sdist ────────────────────────────────────── dist/pyospackage-0.1.tar.gz ────────────────────────────────────── wheel ────────────────────────────────────── dist/pyospackage-0.1-py3-none-any.whl" +msgstr "" + +#: ../../tutorials/publish-pypi.md:186 +msgid " Congratulations - you've created your Python package distribution files " +msgstr "" + +#: ../../tutorials/publish-pypi.md:188 +msgid "You've now built your Python package and created your package distribution files. The next step is to setup your account on TestPyPI so you can publish your package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:191 +msgid "Step 3. Setup your TestPyPI account" +msgstr "" + +#: ../../tutorials/publish-pypi.md:193 +msgid "Next, you'll setup an account on TestPyPI. Remember that you are using TestPyPI here instead of the real PyPI as a way to safely learn how to publish a package without accidentally \"releasing\" your package before it's ready." +msgstr "" + +#: ../../tutorials/publish-pypi.md:197 +msgid "TestPyPI vs. PyPI" +msgstr "" + +#: ../../tutorials/publish-pypi.md:198 +msgid "If you have a package that you are confident belongs on PyPI, all of the steps below will also work for you. When you publish using Hatch, you will call `hatch publish` to publish directly to PyPI instead of `hatch publish -r test` which publishes to TestPyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:201 +msgid "[Open up a web browser and go to the TestPyPI website](https://test.pypi.org/)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:202 +msgid "[Create an account](https://test.pypi.org/account/register/) if you don't already have one. Be sure to store your password in a safe place!" +msgstr "" + +#: ../../tutorials/publish-pypi.md:203 +msgid "Once you have an account setup, login to it." +msgstr "" + +#: ../../tutorials/publish-pypi.md:204 +msgid "Search on [https://test.pypi.org/](https://test.pypi.org/) (and also on [https://pypi.org/](https://pypi.org/)) to ensure that the package name that you have selected doesn't already exist. If you are using our test pyosPackage, then we suggest that you add your name or GitHub username to the end of the package name to ensure it's unique." +msgstr "" + +#: ../../tutorials/publish-pypi.md:206 +msgid "Example: `pyosPackage_yourNameHere`." +msgstr "" + +#: ../../tutorials/publish-pypi.md:0 +msgid "Renaming your project before publishing" +msgstr "" + +#: ../../tutorials/publish-pypi.md:211 +msgid "Required" +msgstr "" + +#: ../../tutorials/publish-pypi.md:213 +msgid "Search your publishing location(s) to make sure your new name isn't taken ([TestPyPI](https://test.pypi.org/), [PyPI](https://pypi.org/), [conda-forge](https://conda-forge.org/packages/))" +msgstr "" + +#: ../../tutorials/publish-pypi.md:214 +msgid "Update the project name in your pyproject.toml file (e.g. `name = \"pyospackage_yourNameHere\"`)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:215 +msgid "Update the module folder name to be the same (e.g. `src/pyospackage_yourNameHere`)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:216 +msgid "Rebuild your project (`hatch build`)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:217 +msgid "Publish your package to capture the name (continue this tutorial!)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:219 +msgid "Recommended" +msgstr "" + +#: ../../tutorials/publish-pypi.md:221 +msgid "Update the GitHub repository name to align with the new package name" +msgstr "" + +#: ../../tutorials/publish-pypi.md:222 +msgid "Update your local project folder to match the new package name (e.g. `pyospackage_yourNameHere/src`)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:223 +msgid "Update mentions of your repository name in other files (e.g. `README.md`)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:227 +msgid "This is a screenshot of the TestPyPI website. At the top in the search bar, you can see the search for pyosPackage. The search return says there were no results for pyosPackage Did you mean probpackage" +msgstr "" + +#: ../../tutorials/publish-pypi.md:229 +msgid "Before you try to upload to TestPyPI, check to see if the name of your package is already taken. You can do that using the search box at the top of the TestPyPI website." +msgstr "" + +#: ../../tutorials/publish-pypi.md:233 +msgid "Setup 2-factor (2FA) authentication" +msgstr "" + +#: ../../tutorials/publish-pypi.md:235 +msgid "2-factor authentication is a secure login process that allows you to use a backup device that only you can access to validate that the person logging in is really you. It addresses the issue of password phishing where someone else gains access to a password and can login to your account." +msgstr "" + +#: ../../tutorials/publish-pypi.md:238 +msgid "This matters on PyPI because someone could login to your account and upload a version of your package that has security issues. These issues will then impact all of your users when they download and install that version of the package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:240 +msgid "2-factor authentication is required for PyPI authentication as of 1 January 2024." +msgstr "" + +#: ../../tutorials/publish-pypi.md:244 +msgid "Step 4. Create a package upload token" +msgstr "" + +#: ../../tutorials/publish-pypi.md:246 +msgid "To upload your package to TestPyPI (or PyPI), you will need to create a token for your account first, and should then create a package-specific token. (If you completed this step previously, you can reuse the tokens when you upload your package again.)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:248 +msgid "Why create package-specific tokens?" +msgstr "" + +#: ../../tutorials/publish-pypi.md:250 +msgid "It's ideal to create a package-specific token. When you create an account-wide token this allows anyone with access to the account to then access all of your TestPyPI (or PyPI) projects. By creating a package-specific token, you are limiting the scope of the token to only your specific package. This is just a safe way to set things up for you particularly if you are collaborating with others on package development." +msgstr "" + +#: ../../tutorials/publish-pypi.md:253 +msgid "Follow the steps below to create your token." +msgstr "" + +#: ../../tutorials/publish-pypi.md:255 +msgid "Login to TestPyPI and go to your account settings" +msgstr "" + +#: ../../tutorials/publish-pypi.md:256 +msgid "Scroll down to the **API tokens** section" +msgstr "" + +#: ../../tutorials/publish-pypi.md:257 +msgid "Click on the **Add API Token** button" +msgstr "" + +#: ../../tutorials/publish-pypi.md:258 +msgid "If you are new to using TestPyPI and don't have any packages there yet, OR if you have other packages on TestPyPI but are uploading a new package, you will need to create an account-wide token." +msgstr "" + +#: ../../tutorials/publish-pypi.md:259 +msgid "When you create your token, be sure to copy the token value and store it in a secure place before closing that browser." +msgstr "" + +#: ../../tutorials/publish-pypi.md:261 +msgid "Your token should look something like this:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:263 +msgid "`pypi-abunchofrandomcharactershere...`" +msgstr "" + +#: ../../tutorials/publish-pypi.md:265 +msgid "It should start with `pypi` followed by a dash and a bunch of characters." +msgstr "" + +#: ../../tutorials/publish-pypi.md:267 +msgid "Upload to TestPyPI using Hatch" +msgstr "" + +#: ../../tutorials/publish-pypi.md:269 +msgid "Once you have your token, you are ready to publish to TestPyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:272 +msgid "Run `hatch publish -r test`" +msgstr "" + +#: ../../tutorials/publish-pypi.md:274 +msgid "`-r` stands for repository. In this case because you are publishing to TestPyPI you will use `-r test`. Hatch will then ask for a username and credentials." +msgstr "" + +#: ../../tutorials/publish-pypi.md:276 +msgid "Add the word `__token__` for your username. This tells TestPyPI that you are using a token value rather than a username." +msgstr "" + +#: ../../tutorials/publish-pypi.md:277 +msgid "Paste your TestPyPI token value in at the `Enter your credentials` prompt:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:288 +msgid "If your credentials are valid, and you have already run `hatch build` and thus have your 2 distribution files in a `dist/` directory then Hatch will publish your package to TestPyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:292 +msgid "Hatch also has a caching system so once you enter your credentials it will remember them." +msgstr "" + +#: ../../tutorials/publish-pypi.md:295 +msgid "Install your package from TestPyPI" +msgstr "" + +#: ../../tutorials/publish-pypi.md:297 +msgid "Once your package upload is complete, you can install it from TestPyPI. You can find the installation instructions on the TestPyPI landing page for your newly uploaded package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:302 +msgid "A screenshot of the TestPyPI page for pyosPackage. It says pyosPackage 0.1.0 at the top with the pip install instructions below. The landing page of the package has information from the package's README file." +msgstr "" + +#: ../../tutorials/publish-pypi.md:304 +msgid "This is an example landing page for the pyosPackage that was just uploaded. Notice at the top of the page there are instructions for how to install the package from TestPyPI. You can simply copy that code and use it to install your package from TestPyPI locally." +msgstr "" + +#: ../../tutorials/publish-pypi.md:307 +msgid "As an example, [check out our pyOpenSci pyosPackage landing page on TestPyPI](https://test.pypi.org/project/pyosPackage/). Notice that the page has information about the current package version and also installation instructions as follows:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:311 +msgid "`python -m pip install -i https://test.pypi.org/simple/ pyosPackage`" +msgstr "" + +#: ../../tutorials/publish-pypi.md:314 +msgid "Publishing to TestPyPI vs PyPI While you can install from TestPyPI it's not recommended that you publish to TestPyPI as a permanent way to install your package. In fact, you cannot, because TestPyPI may delete accounts after a time. TestPyPI is a perfect place to learn how to publish your package and test the installation process. But your end goal should be to publish to PyPI once you have figured out your workflow and your package is ready to deploy." +msgstr "" + +#: ../../tutorials/publish-pypi.md:318 +msgid "Time to install your package" +msgstr "" + +#: ../../tutorials/publish-pypi.md:320 +msgid "On your computer, activate the development environment that you wish to install your newly published package in." +msgstr "" + +#: ../../tutorials/publish-pypi.md:322 +msgid "Run the installation instructions for your package from TestPyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:0 +msgid "Conda" +msgstr "" + +#: ../../tutorials/publish-pypi.md:0 +msgid "venv Mac / Linux" +msgstr "" + +#: ../../tutorials/publish-pypi.md:346 +msgid "The value of end-to-end tools like hatch, flit and poetry" +msgstr "" + +#: ../../tutorials/publish-pypi.md:347 +msgid "In this lesson you are using Hatch and hatchling to create, build and publish your Python package. [Click here to learn about other packaging tools in the ecosystem.](../package-structure-code/python-package-build-tools.md)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:351 +msgid "teach them to setup trusted publisher for actions... in the actions lesson https://pypi.org/help/#twofa" +msgstr "" + +#: ../../tutorials/publish-pypi.md:354 +msgid "from PyPI: https://pypi.org/help/#apitoken - You can create a token for an entire PyPI account, in which case, the token will work for all projects associated with that account. Alternatively, you can limit a token's scope to a specific project." +msgstr "" + +#: ../../tutorials/publish-pypi.md:357 +msgid "Package-specific token vs trusted publisher" +msgstr "" + +#: ../../tutorials/publish-pypi.md:359 +msgid "For long run maintenance of your package, you have two options related to PyPI publication." +msgstr "" + +#: ../../tutorials/publish-pypi.md:362 +msgid "You can create a package-specific token which you will use to publish your package (manually) to PyPI. This is a great option if you don't wish to automate your PyPI publication workflow." +msgstr "" + +#: ../../tutorials/publish-pypi.md:363 +msgid "You can also create an automated publication workflow on GitHub using GitHub Actions. This is a great way to make the publication process easier and it also supports a growing maintainer team. In this case we suggest you don't worry about the token and instead setup a specific GitHub Actions that publishes your package when you make a release. You can then create a \"trusted publisher\" workflow on PyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:365 +msgid "You will learn how to create the automated trusted publisher workflow in a followup lesson." +msgstr "" + +#: ../../tutorials/publish-pypi.md:368 +msgid "OPTIONAL: If you want to use a manual token-based publication workflow" +msgstr "" + +#: ../../tutorials/publish-pypi.md:370 +msgid "If you plan to use your token regularly to publish to PyPI, we strongly recommend going through the above steps again to create a token specific to your new package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:373 +msgid "To do this:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:374 +msgid "Go to TestPyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:375 +msgid "Navigate to the \"Your Projects\" section of your account" +msgstr "" + +#: ../../tutorials/publish-pypi.md:376 +msgid "Click on the manage button for the project that you wish to add a token for" +msgstr "" + +#: ../../tutorials/publish-pypi.md:377 +msgid "Go to settings" +msgstr "" + +#: ../../tutorials/publish-pypi.md:378 +msgid "Click on \"Create a token for your-package-name-here\"" +msgstr "" + +#: ../../tutorials/publish-pypi.md:379 +msgid "Create the token and follow the steps above publish your package using the repository specific token." +msgstr "" + +#: ../../tutorials/publish-pypi.md:381 +msgid "And you're all done!" +msgstr "" + +#: ../../tutorials/publish-pypi.md:383 +msgid "You have published your package to TestPyPI!" +msgstr "" + +#: ../../tutorials/publish-pypi.md:385 +msgid "Congratulations. You have now successfully published your package to TestPyPI. If you have a package that is ready for real-world use on the real PyPI, then you can follow the same steps (with the differences noted above) to publish it on PyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:387 +msgid "Once you publish on PyPI, you can then easily add your package to the conda-forge ecosystem using the [grayskull](https://conda-forge.org/blog/posts/2020-03-05-grayskull/) tool." +msgstr "" + +#: ../../tutorials/publish-pypi.md:389 +msgid "You will learn how to do that in the next lesson." +msgstr "" + +#: ../../tutorials/publish-pypi.md:396 +msgid "https://docs.python.org/3/library/venv.html" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:1 +msgid "Make your Python package PyPI ready - pyproject.toml" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:3 +msgid "In [the installable code lesson](installable-code), you learned how to add the bare minimum information to a `pyproject.toml` file to make it installable. You then learned how to [publish a bare minimum version of your package to PyPI](publish-pypi.md)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:5 +msgid "Following that you learned how to add a:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:6 +msgid "[README.md](add-readme)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:7 +msgid "[LICENSE](add-license-coc) and" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:8 +msgid "[CODE_OF_CONDUCT](add-coc)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:10 +msgid "to the root of your project directory." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:12 +msgid "To enhance the visibility of your package on PyPI and provide more information about its compatibility with Python versions, project development status, and project maintainers, you should add additional metadata to your `pyproject.toml` file. This lesson will guide you through the process." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:24 +msgid "More about the `pyproject.toml` file and how it's used to store different types of metadata about your package" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:25 +msgid "How to declare information (metadata) about your project to help users find and understand it on PyPI." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:27 +msgid "If you wish to learn more about the `pyproject.toml` format, [check out this page. ](../package-structure-code/pyproject-toml-python-package-metadata.md)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:0 +msgid "Click for lesson takeaways" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:34 +msgid "When creating your pyproject.toml file, consider the following:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:36 +msgid "There are only two required metadata tables that you need to install and publish your Python package:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:37 +msgid "**[build-system]**" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:38 +msgid "**[project]**." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:39 +msgid "The **[project]** table stores your package's metadata. Within the **[project]** table, There are only two _required_ fields:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:40 +msgid "**name=**" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:41 +msgid "**version=**" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:42 +msgid "You should add more metadata to the `[project]` table as it will make it easier for users to find your project on PyPI. And it will also make it easier for installers to understand how to install your package." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:43 +msgid "When you are adding classifiers to the **[project]** table, only use valid values from [PyPI's classifier page](https://PyPI.org/classifiers/). An invalid value here will raise an error when you build and publish your package on PyPI." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:44 +msgid "There is no specific order for tables in the `pyproject.toml` file. However, fields need to be placed within the correct tables. For example `requires =` always need to be in the **[build-system]** table." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:45 +msgid "We suggest that you include your **[build-system]** table at the top of your `pyproject.toml` file." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:50 +msgid "The `pyproject.toml` file is a human and machine-readable file that serves as the primary configuration file for your Python package." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:54 +msgid "[Building your package](build-package) is the step that created the distribution files that are required for you to publish to PyPI." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:58 +msgid "About the .toml format" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:60 +msgid "The **pyproject.toml** file is written in [TOML (Tom's Obvious, Minimal Language) format](https://toml.io/en/). TOML is an easy-to-read structure that is based on key/value pairs. Each section in the **pyproject.toml** file contains a `[table identifier]`. The TOML format can be compared to other structured formats such as`.json`. However, the TOML format was designed to be easier to read for humans." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:62 +msgid "Below you can see the `[build-system]` table. Within that table there are two required key/value pairs." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:65 +msgid "`requires =` is the key and the value is `[\"hatchling\"]` within the `[build-system]` array specified by square brackets `[]`." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:75 +msgid "What is the pyproject.toml used for?" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:77 +msgid "The pyproject.toml file tells your build tool:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:79 +msgid "What build backend to use to build your package (we are using `hatchling` in this tutorial but there are [many others to choose from](/package-structure-code/python-package-build-tools))." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:80 +msgid "How and where to retrieve your package's version:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:81 +msgid "**statically** where you declare the version `version = \"0.1.0\"` or" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:82 +msgid "**dynamically** where the tool looks to the most recent tag in your history to determine the current version." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:83 +msgid "What dependencies your package needs" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:84 +msgid "What versions of Python your package supports (important for your users)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:86 +msgid "The `pyproject.toml` file also makes it easy for anyone browsing your GitHub repository to quickly understand your package's structure such as:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:89 +msgid "How your package is built," +msgstr "" + +#: ../../tutorials/pyproject-toml.md:90 +msgid "What Python versions and operating systems it supports" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:91 +msgid "What it does," +msgstr "" + +#: ../../tutorials/pyproject-toml.md:92 +msgid "Who maintains it" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:94 +msgid "Finally, the pyproject.toml file is also often used to configure tools such as static type checkers (e.g. mypy) and code formatters/linters (e.g. black, ruff)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:97 +msgid "Check out the [PyPA documentation](https://packaging.python.org/en/latest/tutorials/packaging-projects/#choosing-a-build-backend) if you are interested in setting build configurations for other tools." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:99 +msgid "Note that some build tools may deviate in how they store project metadata. As such you may want to refer to their documentation if you decide to use a tool other than Hatch and hatchling. We have selected hatchling and hatch as our tool of choice for this tutorial as it adheres to PyPA rules and guidelines." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:103 +msgid "How is pyproject.toml metadata used?" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:105 +msgid "The pyproject.toml file is the file that your build tool uses to populate a `METADATA` that is included in your Python distribution files that get published to PyPI. This `METADATA` file is then used by PyPI to populate your package's PyPI landing page and help users filter through the tens of thousands of packages published there." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:108 +msgid "Image showing the left side bar of PyPI for the package xclim. The section at the top says Classifier. Below there is a list of items including Development status, intended audience, License, natural language, operating system, programming language and topic. Below each of those sections are various classifier options.\" width=\"300px\">" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:113 +msgid "When you add the classifier section to your pyproject.toml and your package is built, the build tool organizes the metadata into a format that PyPI can understand and represent on your PyPI landing page. These classifiers also allow users to sort through packages by version of python they support, categories and more." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:119 +msgid "A more in-depth overview of pyproject.toml files" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:121 +msgid "[Our guidebook page has a more in depth overview of this file](../package-structure-code/pyproject-toml-python-package-metadata/)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:124 +msgid "How to update your pyproject.toml file" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:126 +msgid "In the last lesson, you created a bare-bones pyproject.toml file that contained the core elements needed to build your package:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:130 +msgid "A `[build-system]` table where you defined your project's backend build tool (`hatchling`)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:131 +msgid "A `[project]` table where you defined your project's version and name." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:133 +msgid "The `pyproject.toml` file that you created, looked like this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:145 +msgid "Your next step is to add additional recommended metadata fields that will both help users find your package on PyPI and also better describe the scope of your package. Once you add this metadata, you don't have to do it again. These metadata fields will only be updated periodically when you do something such as:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:148 +msgid "drop a package dependency" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:149 +msgid "modify what Python versions your package supports." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:151 +msgid "More on hatchling" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:154 +msgid "The documentation for the hatchling back-end is [here](https://hatch.pypa.io/latest/config/metadata/)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:157 +msgid "Step 1: Add Author, maintainer and project description" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:159 +msgid "After completing the [installable code tutorial](installable-code), you should have a pyproject.toml file with a project name and a version in the `[project]` table." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:167 +msgid "Add the following to your table:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:169 +msgid "A **description** of your package. This should be a single line and should briefly describe the goal of your package using non technical terms if as all possible!" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:170 +msgid "package **authors**" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:171 +msgid "package **maintainers**" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:173 +msgid "The `description` is just a string like the other values you've set:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:184 +msgid "When you add authors and maintainers you need to use a format that will look like a Python list with a dictionary within it:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:198 +msgid "Author names & emails" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:202 +msgid "There is a quirk with PyPI for authors that have names but not emails in the pyproject.toml. If you are missing the email for one or more authors or maintainers, like this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:211 +msgid "Then we suggest that you only provide names in your list of names to ensure that everything renders properly on your PyPI page - like this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:220 +msgid "don't have emails for everyone, we suggest that you only add names." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:223 +msgid "Your `pyproject.toml` file now should look like the example below. It is OK if you only have 1 author and the same author is also maintainer of your package:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:0 +msgid "Learn More: What's the difference between author and maintainer in open source?" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:251 +msgid "When adding maintainers and authors, you may want to think about the difference between the two." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:253 +msgid "Authors generally include people who:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:254 +msgid "originally created / designed developed the package and" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:255 +msgid "people who add new functionality to the package." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:257 +msgid "Whereas maintainers are the people that are currently, actively working on the project. It is often the case that there is overlap in authors and maintainers. As such these lists may be similar or the same." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:259 +msgid "A good example of when the lists might diverge is sometimes you have a package where an initial author developed it and then stepped down as a maintainer to move on to other things. This person may continue to be considered an author but no longer actively maintains the package." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:261 +msgid "It is important to note that there are many ways to define author vs maintainer and we don't prescribe a single approach in this tutorial." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:263 +msgid "However, we encourage you to consider carefully, for PyPI publication, who you want to have listed as authors and maintainers on your PyPI landing page." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:267 +msgid "Step 2: Add README and license" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:269 +msgid "In the previous lessons, you added both a [README.md](add-readme) file and a [LICENSE](add-license-coc) to your package repository. Once you have those files, you can add them to your pyproject.toml file as links following the example below." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:297 +msgid "Step 3: Specify Python version with `requires-python`" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:299 +msgid "Add the `requires-python` field to your `pyproject.toml` `[project]` table. The `requires-python` field helps pip identify which Python versions that your package supports. It is set to a single value. The [packaging specification](https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata-requires-python) defines`requires-python` as a string that uses version specifiers. Most projects will specify the oldest Python version supported by the package. In some advanced cases, an upper bound is set to indicate which future Python versions, if any, will be supported." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:331 +msgid "Step 4: Specify Dependencies" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:333 +msgid "Next add your dependencies table to the project table. The `dependencies =` section contains a list (or array in the toml language) of the Python packages that your package requires to run properly in a Python environment. Similar to the requirements listed in the `[build-system]` table above:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:341 +msgid "dependencies are added in an array (similar to a Python list) structure." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:347 +msgid "A dependency can be limited to specific versions using a **version specifier.** If the dependency has no version specifier after the dependency name, your package can use any version of the dependent package. Code changes over time, bugs are fixed, APIs change, and so it's good to be clear about which version of the dependency you wrote your code to be compatible with - a package you wrote this year probably isn't compatible with numpy v0.0.1!" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:351 +msgid "[Learn more about various ways to specify ranges of package versions here.](https://packaging.python.org/en/latest/specifications/version-specifiers/#id5)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:353 +msgid "The most common version specifier is a **lower bound,** allowing any version higher than the specified version. Ideally you should set this to the lowest version that is still compatible with your package, but in practice for new packages this is often set at the version that was current at the time the package was written[^lowerbound]." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:358 +msgid "Lower bounds look like this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:364 +msgid "Commas are used to separate individual dependencies, and each package in your `dependencies` section can use different types of version specifiers:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:375 +msgid "Your `pyproject.toml` file will now look like this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:405 +msgid "Pin dependencies with caution" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:406 +msgid "\"Pinning\" a dependency means setting it to a specific version, like this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:408 +msgid "`numpy == 1.0`." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:410 +msgid "If you are building a library package that other developers will depend upon, you must be cautious before pinning to a precise dependency version. Applications, such as production websites, will often pin their dependencies since other packages will not depend on their project. This is because users will be installing your package into various environments. A dependency pinned to a single specific version can make resolving a Python environment more challenging. As such only pin dependencies to a specific version if you absolutely need to do so." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:418 +msgid "Similarly, you should be cautious when specifying an upper bound on a package. These two specifications are equivalent:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:426 +msgid "One build tool that you should be aware of that pins dependencies to an upper bound by default is Poetry. [Read more about how to safely add dependencies with Poetry, here.](challenges-with-poetry)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:429 +msgid "Step 5: Add PyPI classifiers" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:431 +msgid "Next you will add classifiers to your `pyproject.toml` file. The value for each classifier that you add to your `pyproject.toml` file must come from the list of [PyPI accepted classifier values found here](https://PyPI.org/classifiers/). Any deviations in spelling and format will cause issues when you publish to PyPI." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:433 +msgid "What happens when you use incorrect classifiers?" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:436 +msgid "If you do not [use standard classifier values](https://PyPI.org/classifiers/), when you try to publish your package on PyPI it will be rejected. 😔 Don't worry if PyPI rejects you on your first try! It has happened to all of us." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:439 +msgid "Review that list and add items below to your `pyproject.toml` file:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:441 +msgid "development status" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:442 +msgid "intended audiences" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:443 +msgid "topic" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:444 +msgid "license and" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:445 +msgid "programming language support" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:447 +msgid "The classifier key should look something like the example below. A few notes:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:449 +msgid "Your classifier values might be different depending upon the license you have selected for your package, your intended audience, development status of your package and the Python versions that you support" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:450 +msgid "You can add as many classifiers as you wish as long as you use the [designated PyPI classifier values](https://PyPI.org/classifiers/)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:490 +msgid "Note that while classifiers are not required in your `pyproject.toml` file, they will help users find your package. As such we strongly recommend that you add them." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:492 +msgid "Step 6: Add the `[project.urls]` table" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:494 +msgid "Finally, add the project.urls table to your pyproject.toml file." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:496 +msgid "`project.urls` contains links that are relevant for your project. You might want to include:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:498 +msgid "**Homepage:** A link to your published documentation for your project. If you are working through this tutorial, then you may not have this link yet. That's ok, you can skip it for the time being." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:499 +msgid "**Bug reports:** a link to your issues / discussions or wherever you want users to report bugs." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:500 +msgid "**Source:** the GitHub / GitLab link for your project." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:546 +msgid "There are many other urls that you can add here. Check out the [README file here for an overview](https://github.com/patrick91/links-demo)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:549 +msgid "Putting it all together - your completed pyproject.toml file" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:551 +msgid "Below is an example of a complete `pyproject.toml` file that is commented with all of the sections we discussed above." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:0 +msgid "Appendix - Click for a fully commented pyproject.toml file" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:601 +msgid "Below is a fully commented pyproject.toml file if you want to use it for reference." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:666 +msgid "Example `pyproject.toml` files" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:668 +msgid "Below are some examples of `pyproject.toml` files from various packages in the scientific and pyOpenSci ecosystem." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:669 +msgid "[PyPA's fully documented example pyproject.toml file](https://github.com/pypa/sampleproject/blob/main/pyproject.toml)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:670 +msgid "[taxpasta has a nicely organized pyproject.toml file and is a pyOpenSci approved package](https://github.com/taxprofiler/taxpasta/blob/f9f6eea2ae7dd08bb60a53dd49ad77e4cf143573/pyproject.toml)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:676 +msgid "At this point you've created:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:678 +msgid "A [README.md](add-readme) file for your package" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:679 +msgid "A [CODE_OF_CONDUCT.md](add-coc) file to support your user community" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:680 +msgid "And a [LICENSE](add-license-coc) file which provides legal boundaries around how people can and can't use your software" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:682 +msgid "You also learned [how to publish your package to (test)PyPI](publish-pypi)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:684 +msgid "Publish a new version of your package to PyPI" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:686 +msgid "You are now ready to publish a new version of your Python package to (test) PyPI. When you do this you will see that the landing page for your package now contains a lot more information." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:688 +msgid "Try to republish now." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:690 +msgid "First, update the version of your package in your pyproject toml file. Below version is updated from `0.1` to `0.1.1`." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:703 +msgid "Now use hatch to publish the new version of your package to test.PyPI.org." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:710 +msgid "Next (optional) step - publishing to conda-forge" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:712 +msgid "You now have all of the skills that you need to publish your package to PyPI." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:715 +msgid "If you also want to publish your package on conda-forge (which is a channel within the conda ecosystem), you will learn how to do that in the next lesson." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:719 +msgid "Really good resources from jeremiah https://daniel.feldroy.com/posts/2023-08-pypi-project-urls-cheatsheet useful (and the linked links-demo even more so)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:356 +msgid "Some packaging tools will do this for you when you add a dependency using their cli interface. For example [`poetry add`](https://python-poetry.org/docs/cli/#add) will add the most recent version with a `^` specifier, and [`pdm add`](https://pdm-project.org/latest/reference/cli/#add) will add the most recent version with `>=`." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:1 +msgid "Using Hatch to Migrate setup.py to a pyproject.toml" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:3 +msgid "Hatch can be particularly useful to generate your project's `pyproject.toml` if your project already has a `setup.py`." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:5 +msgid "Note" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:8 +msgid "This step is not necessary and is only useful if your project already has a `setup.py` file defined." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:9 +msgid "If your project does not already define a `setup.py` see [Make your Python code installable](installable-code.md)" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:17 +msgid "The process of using Hatch to transition to using `pyproject.toml` for projects that already have a `setup.py` defined." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:20 +msgid "What is Hatch?" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:22 +msgid "Hatch is a Python package manager designed to streamline the process of creating, managing, and distributing Python packages. It provides a convenient CLI (Command-Line Interface) for tasks such as creating new projects, managing dependencies, building distributions, and publishing packages to repositories like PyPI." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:28 +msgid "See [Get to know Hatch](get-to-know-hatch.md) for more information." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:31 +msgid "Prerequisites" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:33 +msgid "Before we begin, ensure that you have Hatch installed on your system. You can install it via pip:" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:39 +msgid "Sample Directory Tree" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:41 +msgid "Let's take a look at a sample directory tree structure before and after using `hatch init`:" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:43 +msgid "Before `hatch init`" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:59 +msgid "After `hatch init`" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:77 +msgid "As you can see, the main change after running `hatch init` is the addition of the `pyproject.toml` file in the project directory." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:79 +msgid "Step-by-Step Guide" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:81 +msgid "Now, let's walk through the steps to use Hatch to create a `pyproject.toml` file for your project." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:83 +msgid "**Navigate to Your Project Directory**: Open your terminal or command prompt and navigate to the directory where your Python project is located." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:85 +msgid "**Initialize Hatch**: Run the following command to initialize Hatch in your project directory:" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:91 +msgid "**Review and Customize**: After running the previous command, Hatch will automatically generate a `pyproject.toml` file based on your existing project configuration. Take some time to review the contents of the generated `pyproject.toml` file. You may want to customize certain settings or dependencies based on your project's requirements (see [pyproject.toml tutorial](pyproject-toml.md) for more information about the `pyproject.toml`)." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:93 +msgid "**Verify**: Verify that the `pyproject.toml` file accurately reflects your project configuration and dependencies. You can manually edit the file if needed, but be cautious and ensure that the syntax is correct." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:95 +msgid "**Delete setup.py**: Since we're migrating to using `pyproject.toml` exclusively, the `setup.py` file becomes unnecessary. You can safely delete it from your project directory." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:97 +msgid "**Test Build**: Before proceeding further, it's essential to ensure that your project builds successfully using only the `pyproject.toml` file. Run the following command to build your project:" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:103 +msgid "This command will build your project based on the specifications in the `pyproject.toml` file. Make sure to check for any errors or warnings during the build process." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:105 +msgid "**Test Existing Functionality**: After successfully building your project with `pyproject.toml`, it's crucial to ensure that your project's existing functionality remains intact. Run any pre-existing tests to verify that everything still works as expected." +msgstr "" + diff --git a/locales/ja/LC_MESSAGES/messages.po b/locales/ja/LC_MESSAGES/messages.po new file mode 100644 index 00000000..2d6f87bf --- /dev/null +++ b/locales/ja/LC_MESSAGES/messages.po @@ -0,0 +1,3972 @@ +msgid "" +msgstr "" +"Project-Id-Version: pyos-python-package-guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-04-30 18:44-0600\n" +"PO-Revision-Date: 2025-05-01 18:41\n" +"Last-Translator: \n" +"Language-Team: Japanese\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=1; plural=0;\n" +"X-Crowdin-Project: pyos-python-package-guide\n" +"X-Crowdin-Project-ID: 785976\n" +"X-Crowdin-Language: ja\n" +"X-Crowdin-File: /translation2/locales/templates/LC_MESSAGES/tutorials.pot\n" +"X-Crowdin-File-ID: 50\n" +"Language: ja_JP\n" + +#: ../../tutorials/add-license-coc.md:1 +msgid "Add a `LICENSE` & `CODE_OF_CONDUCT` to your Python package" +msgstr "" + +#: ../../tutorials/add-license-coc.md:3 +msgid "In the [previous lesson](add-readme) you:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:5 +msgid " Created a basic `README.md` file for your scientific Python package" +msgstr "" + +#: ../../tutorials/add-license-coc.md:7 +msgid " Learned about the core components that are useful to have in a `README` file." +msgstr "" + +#: ../../tutorials/add-license-coc.md:9 +#: ../../tutorials/add-readme.md:10 +msgid "Learning objectives" +msgstr "" + +#: ../../tutorials/add-license-coc.md:12 +#: ../../tutorials/add-readme.md:12 +#: ../../tutorials/installable-code.md:41 +#: ../../tutorials/pyproject-toml.md:22 +#: ../../tutorials/setup-py-to-pyproject-toml.md:15 +msgid "In this lesson you will learn:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:14 +msgid "How to select a license and add a `LICENSE` file to your package repository, with a focus on the GitHub interface." +msgstr "" + +#: ../../tutorials/add-license-coc.md:15 +msgid "How to add a `CODE_OF_CONDUCT` file to your package repository." +msgstr "" + +#: ../../tutorials/add-license-coc.md:16 +msgid "How you can use the Contributors Covenant website to add generic language as a starting place for your `CODE_OF_CONDUCT`." +msgstr "" + +#: ../../tutorials/add-license-coc.md:19 +msgid "What is a license?" +msgstr "" + +#: ../../tutorials/add-license-coc.md:21 +msgid "A license contains legal language about how users can use and reuse your software. To set the `LICENSE` for your project, you:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:23 +msgid "Create a `LICENSE` file in your project directory that specifies the license that you choose for your package." +msgstr "" + +#: ../../tutorials/add-license-coc.md:24 +msgid "Reference that file in your `pyproject.toml` data where metadata are set." +msgstr "" + +#: ../../tutorials/add-license-coc.md:26 +msgid "By adding the `LICENSE` file to your `pyproject.toml` file, the `LICENSE` will be included in your package's metadata which is used to populate your package's PyPI landing page. The `LICENSE` is also used in your GitHub repository's landing page interface." +msgstr "" + +#: ../../tutorials/add-license-coc.md:28 +msgid "What license should you use?" +msgstr "" + +#: ../../tutorials/add-license-coc.md:30 +msgid "We suggest that you use a permissive license that accommodates the other most commonly used licenses in the scientific Python ecosystem (MIT[^mit] and BSD-3[^bsd3]). If you are unsure, use MIT given it's the generally recommended license on [choosealicense.com](https://choosealicense.com/)." +msgstr "" + +#: ../../tutorials/add-license-coc.md:33 +msgid "Licenses for the scientific Python ecosystem" +msgstr "" + +#: ../../tutorials/add-license-coc.md:34 +msgid "[We discuss licenses for the scientific Python ecosystem in more detail here in our guidebook.](../documentation/repository-files/license-files)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:37 +msgid "Where should the `LICENSE` file live" +msgstr "" + +#: ../../tutorials/add-license-coc.md:39 +msgid "Your `LICENSE` file should be placed at the root of your package's repository. When you add the `LICENSE` at the root, GitHub will automagically discover it and provide users with a direct link to your `LICENSE` file within your GitHub repository." +msgstr "" + +#: ../../tutorials/add-license-coc.md:45 +msgid "Image showing the GitHub repository for SunPy an accepted pyOpenSci package." +msgstr "" + +#: ../../tutorials/add-license-coc.md:47 +msgid "Notice at the top of the README portion of the GitHub landing page, there are three tabs directly linking to the `README` file which is visible, the `CODE_OF_CONDUCT` file and one that specifies the license that SunPy uses. These files are discovered by GitHub because they are placed in the root of the project directory using standard naming conventions." +msgstr "" + +#: ../../tutorials/add-license-coc.md:54 +msgid "How to add a `LICENSE` file to your package directory" +msgstr "" + +#: ../../tutorials/add-license-coc.md:56 +msgid "There are several ways to add a `LICENSE` file:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:58 +msgid "When you create a new repository on GitHub, it will ask you if you wish to add a `LICENSE` file at that time. If you select yes, it will create the file for you." +msgstr "" + +#: ../../tutorials/add-license-coc.md:59 +msgid "You can add a `LICENSE` through the GitHub gui following the [ instructions here](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository)." +msgstr "" + +#: ../../tutorials/add-license-coc.md:60 +msgid "You can add the file manually as we are doing in this lesson." +msgstr "" + +#: ../../tutorials/add-license-coc.md:63 +msgid "If you completed the past lessons including" +msgstr "" + +#: ../../tutorials/add-license-coc.md:65 +msgid "[Making your code installable](installable-code.md) and" +msgstr "" + +#: ../../tutorials/add-license-coc.md:66 +msgid "[publishing your package to PyPI](publish-pypi.md)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:68 +msgid "then you already have a `LICENSE` file containing text for the MIT license in your Python package. Thus you can skip to the next section of this tutorial which walks you through adding a `CODE_OF_CONDUCT`." +msgstr "" + +#: ../../tutorials/add-license-coc.md:70 +msgid "If you don't yet have a `LICENSE` file in your directory, then continue reading." +msgstr "" + +#: ../../tutorials/add-license-coc.md:73 +msgid "How to add a `LICENSE` to your package - the manual way" +msgstr "" + +#: ../../tutorials/add-license-coc.md:75 +msgid "If you don't already have a `LICENSE` file, and you are not yet using a platform such as GitHub or GitLab, then you can create a `LICENSE` file by" +msgstr "" + +#: ../../tutorials/add-license-coc.md:77 +msgid "Create a new file called `LICENSE`. If you are using shell you can type:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:84 +msgid "Go to [choosealicense.com](https://choosealicense.com/)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:85 +msgid "Select permissive license" +msgstr "" + +#: ../../tutorials/add-license-coc.md:86 +msgid "It will suggest that you use the [MIT license](https://choosealicense.com/licenses/mit/)." +msgstr "" + +#: ../../tutorials/add-license-coc.md:87 +msgid "Copy the license text that it provides into your `LICENSE` file that you created above." +msgstr "" + +#: ../../tutorials/add-license-coc.md:88 +msgid "Save your file. You're all done!" +msgstr "" + +#: ../../tutorials/add-license-coc.md:90 +msgid "An overview of licenses in the scientific Python ecosystem" +msgstr "" + +#: ../../tutorials/add-license-coc.md:93 +msgid "In the pyOpenSci [packaging guidebook](../documentation/repository-files/license-files), we provide an overview of licenses in the scientific Python ecosystem. We review why license files are important, which ones are most commonly used for scientific software and how to select the correct license." +msgstr "" + +#: ../../tutorials/add-license-coc.md:95 +msgid "If you want a broad overview of why licenses are important for protecting open source software, [check out this blog post that overviews the legal side of things.](https://opensource.guide/legal/#just-give-me-the-tldr-on-what-i-need-to-protect-my-project)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:0 +msgid "Instructions for adding a `LICENSE` file within the GitHub interface" +msgstr "" + +#: ../../tutorials/add-license-coc.md:0 +msgid "Add license: new GitHub repository" +msgstr "" + +#: ../../tutorials/add-license-coc.md:106 +msgid "When you create a new GitHub repository you can add a `LICENSE` file through the GitHub interface." +msgstr "" + +#: ../../tutorials/add-license-coc.md:111 +msgid "Screenshot of the create new repository interface that GitHub provides. The elements of this are the owner and repository name for the new repo. Below that you can add a description of the repository. Below that you can set it to be public or private. At the bottom of the interface there is an Add a README checkbox where it will add a blank readme file for you. At the very bottom there is a line to add a .gitignore file and another to choose a license." +msgstr "" + +#: ../../tutorials/add-license-coc.md:113 +msgid "Image showing the GitHub interface that allows you to add a `LICENSE` and `README` file when you create a new repository." +msgstr "" + +#: ../../tutorials/add-license-coc.md:0 +msgid "Add `LICENSE`: Existing GitHub repository" +msgstr "" + +#: ../../tutorials/add-license-coc.md:119 +msgid "If you already have a GitHub repository for your package, then you can add a `LICENSE` using the GitHub interface by adding a new file to the repository." +msgstr "" + +#: ../../tutorials/add-license-coc.md:121 +msgid "Follow the instructions to select and add a license to your repository on the [GitHub LICENSE page](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository) ." +msgstr "" + +#: ../../tutorials/add-license-coc.md:122 +msgid "Once you have added your `LICENSE` file, be sure to sync your git local repository with the repository on GitHub.com. This means running `git pull` to update your local branch." +msgstr "" + +#: ../../tutorials/add-license-coc.md:125 +msgid "Image showing what the LICENSE file looks like in the GItHub interface. At the top you can see the actual license which in this image is BSD 3-clause New or revised license. Then there is some text describing both what the license is and the associated permissions for that specific license. At the bottom of the image, the actual text for the license is shown in the LICENSE file." +msgstr "" + +#: ../../tutorials/add-license-coc.md:127 +msgid "You can view a summary of the `LICENSE` chosen on your project's GitHub landing page." +msgstr "" + +#: ../../tutorials/add-license-coc.md:134 +msgid "Now you know how to add a `LICENSE` to your project. Next, you'll learn about the `CODE_OF_CONDUCT.md` file and how to add it to your package directory." +msgstr "" + +#: ../../tutorials/add-license-coc.md:139 +msgid "What is a code of conduct file?" +msgstr "" + +#: ../../tutorials/add-license-coc.md:141 +msgid "A `CODE_OF_CONDUCT` file is used to establish guidelines for how people in your community interact." +msgstr "" + +#: ../../tutorials/add-license-coc.md:143 +msgid "This file is critical to supporting your community as it grows. The `CODE_OF_CONDUCT`:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:146 +msgid "Establishes guidelines for how users and contributors interact with each other and you in your software repository." +msgstr "" + +#: ../../tutorials/add-license-coc.md:147 +msgid "Identifies negative behaviors that you don't want in your interactions." +msgstr "" + +#: ../../tutorials/add-license-coc.md:149 +msgid "You can use your code of conduct as a tool that can be referenced when moderating challenging conversations." +msgstr "" + +#: ../../tutorials/add-license-coc.md:151 +msgid "What to put in your `CODE_OF_CONDUCT` file" +msgstr "" + +#: ../../tutorials/add-license-coc.md:153 +msgid "If you are unsure of what language to add to your `CODE_OF_CONDUCT` file, we suggest that you adopt the [contributor covenant language](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) as a starting place." +msgstr "" + +#: ../../tutorials/add-license-coc.md:156 +msgid "![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:156 +msgid "Contributor Covenant" +msgstr "" + +#: ../../tutorials/add-license-coc.md:158 +msgid "The `CODE_OF_CONDUCT.md` should be placed at the root of your project directory, similar to the `LICENSE` file." +msgstr "" + +#: ../../tutorials/add-license-coc.md:160 +msgid "How to add a `CODE_OF_CONDUCT` file to your package directory" +msgstr "" + +#: ../../tutorials/add-license-coc.md:162 +msgid "Add a `CODE_OF_CONDUCT.md` file to the root of your repository if it doesn't already exist." +msgstr "" + +#: ../../tutorials/add-license-coc.md:168 +msgid "Visit the [contributor covenant website](https://www.contributor-covenant.org/) and add [the markdown version of their code of conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/code_of_conduct.md) to your `CODE_OF_CONDUCT.md` file. Be sure to fill in any placeholder information. Read the text closely to ensure you both understand it and also agree with its contents!" +msgstr "" + +#: ../../tutorials/add-license-coc.md:170 +msgid "That's it - you've now added a code of conduct to your package directory." +msgstr "" + +#: ../../tutorials/add-license-coc.md:172 +msgid "Additional Code of Conduct resources" +msgstr "" + +#: ../../tutorials/add-license-coc.md:175 +msgid "[ Guide: `CODE_OF_CONDUCT.md` files](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:176 +msgid "[pyOpenSci package guide `CODE_OF_CONDUCT.md` overview](https://www.pyopensci.org/python-package-guide/documentation/repository-files/code-of-conduct-file.html)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:179 +#: ../../tutorials/add-readme.md:233 +#: ../../tutorials/publish-conda-forge.md:463 +#: ../../tutorials/pyproject-toml.md:673 +msgid " Wrap up" +msgstr "" + +#: ../../tutorials/add-license-coc.md:181 +msgid "In this lesson and the [last lesson](add-readme), you have added a:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:183 +msgid "`README` file;" +msgstr "" + +#: ../../tutorials/add-license-coc.md:184 +msgid "`LICENSE` file and a" +msgstr "" + +#: ../../tutorials/add-license-coc.md:185 +msgid "`CODE_OF_CONDUCT` file." +msgstr "" + +#: ../../tutorials/add-license-coc.md:187 +msgid "These are fundamental files needed for every scientific Python package repository. These files help users understand how to use your package and interact with package maintainers." +msgstr "" + +#: ../../tutorials/add-license-coc.md:191 +msgid "In the upcoming lessons, you will:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:193 +msgid "[Add more metadata to your `pyproject.toml` file](pyproject-toml) to support building and publishing your package on PyPI." +msgstr "" + +#: ../../tutorials/add-license-coc.md:194 +msgid "Publish a new version of your Python package to the test PyPI to preview the updated metadata landing page." +msgstr "" + +#: ../../tutorials/add-license-coc.md:199 +#: ../../tutorials/installable-code.md:642 +#: ../../tutorials/publish-conda-forge.md:475 +#: ../../tutorials/publish-pypi.md:394 +msgid "Footnotes" +msgstr "" + +#: ../../tutorials/add-license-coc.md:201 +msgid "https://opensource.org/license/mit/" +msgstr "" + +#: ../../tutorials/add-license-coc.md:202 +msgid "https://opensource.org/license/bsd-3-clause/" +msgstr "" + +#: ../../tutorials/add-readme.md:1 +msgid "Add a README file to your Python package" +msgstr "" + +#: ../../tutorials/add-readme.md:3 +msgid "In the previous lessons you learned:" +msgstr "" + +#: ../../tutorials/add-readme.md:5 +msgid "[What a Python package is](intro.md)" +msgstr "" + +#: ../../tutorials/add-readme.md:6 +msgid "[How to make your code installable](installable-code)" +msgstr "" + +#: ../../tutorials/add-readme.md:7 +msgid "[How to publish your package to (test) PyPI](publish-pypi.md)" +msgstr "" + +#: ../../tutorials/add-readme.md:8 +msgid "[How to publish your package to conda-forge](publish-conda-forge.md)" +msgstr "" + +#: ../../tutorials/add-readme.md:14 +msgid "How to add a **README.md** file to your package." +msgstr "" + +#: ../../tutorials/add-readme.md:15 +msgid "What the core elements of a **README.md** file are." +msgstr "" + +#: ../../tutorials/add-readme.md:18 +msgid "What is a README file?" +msgstr "" + +#: ../../tutorials/add-readme.md:20 +msgid "The `README.md` file is a markdown file located at the root of your project directory that helps a user understand:" +msgstr "" + +#: ../../tutorials/add-readme.md:23 +msgid "You package's name" +msgstr "" + +#: ../../tutorials/add-readme.md:24 +msgid "What the package does. Your README file should clearly state the problem(s) that your software is designed to solve and its target audience." +msgstr "" + +#: ../../tutorials/add-readme.md:25 +msgid "The current development \"state\" of the package (through badges)" +msgstr "" + +#: ../../tutorials/add-readme.md:26 +msgid "How to get started with using your package." +msgstr "" + +#: ../../tutorials/add-readme.md:27 +msgid "How to contribute to your package" +msgstr "" + +#: ../../tutorials/add-readme.md:28 +msgid "How to cite your package" +msgstr "" + +#: ../../tutorials/add-readme.md:30 +msgid "Your **README.md** file is important as it is often the first thing that someone sees before they install your package. The README file is also used to populate your PyPI landing page." +msgstr "" + +#: ../../tutorials/add-readme.md:32 +msgid "Note that there is no specific content structure for README files. However, this tutorial outlines the sections that we suggest that you include in your README file." +msgstr "" + +#: ../../tutorials/add-readme.md:36 +msgid "Create a README.md file for your package" +msgstr "" + +#: ../../tutorials/add-readme.md:38 +msgid "It's time to add a `README.md` file to your project directory." +msgstr "" + +#: ../../tutorials/add-readme.md:40 +msgid "Step 0: Create a README file" +msgstr "" + +#: ../../tutorials/add-readme.md:41 +msgid "To get started, if you don't already have a README.md file in your project directory, create one." +msgstr "" + +#: ../../tutorials/add-readme.md:44 +msgid "If you created your project directory from" +msgstr "" + +#: ../../tutorials/add-readme.md:46 +msgid "a GitHub repository online" +msgstr "" + +#: ../../tutorials/add-readme.md:47 +msgid "using `hatch init`" +msgstr "" + +#: ../../tutorials/add-readme.md:49 +msgid "Then you may already have a README.MD file in your project directory." +msgstr "" + +#: ../../tutorials/add-readme.md:55 +msgid "Step 1: Add the name of your package as the README title" +msgstr "" + +#: ../../tutorials/add-readme.md:57 +msgid "At the top of the `README.md` file, add the name of your package." +msgstr "" + +#: ../../tutorials/add-readme.md:59 +msgid "If you are using markdown it should be a header 1 (H1) tag which is denoted with a single `#` sign." +msgstr "" + +#: ../../tutorials/add-readme.md:61 +msgid "`# Package-title-here`" +msgstr "" + +#: ../../tutorials/add-readme.md:63 +msgid "Step 2: add badges to the top of your README file" +msgstr "" + +#: ../../tutorials/add-readme.md:65 +msgid "It's common for maintainers to add badges to the top of their README files. Badges allow you and your package users to track things like:" +msgstr "" + +#: ../../tutorials/add-readme.md:67 +msgid "Broken documentation and test builds." +msgstr "" + +#: ../../tutorials/add-readme.md:68 +msgid "Versions of your package that are on PyPI and conda." +msgstr "" + +#: ../../tutorials/add-readme.md:69 +msgid "Whether your package has been reviewed and vetted by an organization such as pyOpenSci and/or JOSS." +msgstr "" + +#: ../../tutorials/add-readme.md:71 +msgid "If you have already published your package to pypi.org you can use [shields.io to create a package version badge](https://shields.io/badges/py-pi-version). This badge will dynamically update as you release new versions of your package to PyPI." +msgstr "" + +#: ../../tutorials/add-readme.md:73 +msgid "If not, you can leave the top empty for now and add badges to your README at a later point as they make sense." +msgstr "" + +#: ../../tutorials/add-readme.md:75 +msgid "Step 3: Add a description of what your package does" +msgstr "" + +#: ../../tutorials/add-readme.md:77 +msgid "Below the badges (if you have them), add a section of text that provides an easy-to-understand overview of what your package does." +msgstr "" + +#: ../../tutorials/add-readme.md:81 +msgid "Keep this section short." +msgstr "" + +#: ../../tutorials/add-readme.md:82 +msgid "Try to avoid jargon." +msgstr "" + +#: ../../tutorials/add-readme.md:83 +msgid "Define technical terms that you use to make the description accessible to more people." +msgstr "" + +#: ../../tutorials/add-readme.md:85 +msgid "Remember that the more people understand what your package does, the more people will use it." +msgstr "" + +#: ../../tutorials/add-readme.md:87 +msgid "Step 4: Add package installation instructions" +msgstr "" + +#: ../../tutorials/add-readme.md:89 +msgid "Next, add instructions that tell users how to install your package." +msgstr "" + +#: ../../tutorials/add-readme.md:91 +msgid "For example, can they use pip to install your package? `python -m pip install packagename`" +msgstr "" + +#: ../../tutorials/add-readme.md:94 +msgid "or conda?" +msgstr "" + +#: ../../tutorials/add-readme.md:96 +msgid "`conda install -c conda-forge packagename`." +msgstr "" + +#: ../../tutorials/add-readme.md:98 +msgid "If you haven't yet published your package to pypi.org then you can skip this section and come back and add these instructions later." +msgstr "" + +#: ../../tutorials/add-readme.md:102 +msgid "Step 5: Any additional setup" +msgstr "" + +#: ../../tutorials/add-readme.md:104 +msgid "In some cases, your package users may need to manually install other tools in order to use your package. If that is the case, be sure to add a section on additional setup to your README file." +msgstr "" + +#: ../../tutorials/add-readme.md:109 +msgid "Here, briefly document (or link to documentation for) any additional setup that is required to use your package. This might include:" +msgstr "" + +#: ../../tutorials/add-readme.md:113 +msgid "authentication information, if it is applicable to your package." +msgstr "" + +#: ../../tutorials/add-readme.md:114 +msgid "additional tool installations, such as GDAL." +msgstr "" + +#: ../../tutorials/add-readme.md:117 +msgid "Many packages won't need an additional setup section in their README. In that case you can always skip this section." +msgstr "" + +#: ../../tutorials/add-readme.md:122 +msgid "Step 6: Add a get started section" +msgstr "" + +#: ../../tutorials/add-readme.md:124 +msgid "Next add a get-started section. Within this section, add a small code example that demonstrates importing and using some of the functionality in your package." +msgstr "" + +#: ../../tutorials/add-readme.md:127 +msgid "Provide a fully functional code snippet if possible" +msgstr "" + +#: ../../tutorials/add-readme.md:130 +msgid "It is important to try to make the code examples that you provide your users as useful as possible." +msgstr "" + +#: ../../tutorials/add-readme.md:132 +msgid "Be sure to provide a copy/paste code example that will work as-is when pasted into a Jupyter Notebook or .py file if that is possible." +msgstr "" + +#: ../../tutorials/add-readme.md:134 +msgid "If there are tokens and other steps needed to run your package, be sure to be clear about what those steps are." +msgstr "" + +#: ../../tutorials/add-readme.md:137 +msgid "For the pyosPackage, a short get started demo might look like this:" +msgstr "" + +#: ../../tutorials/add-readme.md:145 +msgid "Or it could simply be a link to a getting started tutorial that you have created. If you don't have this yet, you can leave it empty for the time being." +msgstr "" + +#: ../../tutorials/add-readme.md:148 +msgid "This would also be a great place to add links to tutorials that help users understand how to use your package for common workflows." +msgstr "" + +#: ../../tutorials/add-readme.md:153 +msgid "Step 7: Community section" +msgstr "" + +#: ../../tutorials/add-readme.md:155 +msgid "The community section of your README file is a place to include information for users who may want to engage with your project. This engagement will likely happen on a platform like GitHub or GitLab." +msgstr "" + +#: ../../tutorials/add-readme.md:157 +msgid "In the community section, you will add links to your contributing guide and `CODE_OF_CONDUCT.md`. You will create a [`CODE_OF_CONDUCT.md` file in the next lesson](add-license-coc)." +msgstr "" + +#: ../../tutorials/add-readme.md:160 +msgid "As your package grows you may also have a link to a development guide that contributors and your maintainer team will follow. The development guide outlines how to perform maintenance tasks such as:" +msgstr "" + +#: ../../tutorials/add-readme.md:163 +msgid "running tests" +msgstr "" + +#: ../../tutorials/add-readme.md:164 +msgid "making package releases" +msgstr "" + +#: ../../tutorials/add-readme.md:165 +msgid "building documentation" +msgstr "" + +#: ../../tutorials/add-readme.md:166 +msgid "and more." +msgstr "" + +#: ../../tutorials/add-readme.md:170 +msgid "Step 8: Citation information" +msgstr "" + +#: ../../tutorials/add-readme.md:172 +msgid "Finally it is important to let users know how to cite your package. You can communicate citation information in a few different ways." +msgstr "" + +#: ../../tutorials/add-readme.md:175 +msgid "You can use a tool such as zenodo to create a DOI and associated citation information for your package if it is hosted on a platform such as GitHub. [Check out this short tutorial that covers setting that up.](https://coderefinery.github.io/github-without-command-line/doi/)" +msgstr "" + +#: ../../tutorials/add-readme.md:179 +msgid "Alternatively if you send your package through a peer review process such as the [one lead by pyOpenSci](https://www.pyopensci.org/about-peer-review/index.html). After being accepted by pyOpenSci, if your package is in scope, you can be accepted by the Journal of Open Source Software and get a cross-ref DOI through [our partnership with the Journal of Open Source Software.](https://www.pyopensci.org/about-peer-review/index.html)" +msgstr "" + +#: ../../tutorials/add-readme.md:183 +msgid "The finished README file" +msgstr "" + +#: ../../tutorials/add-readme.md:185 +msgid "Your finished `README.md` file should look something like this:" +msgstr "" + +#: ../../tutorials/add-readme.md:235 +msgid "It's important to consider the information that a new user or contributor might need when creating your `README.md` file. While there is no perfect template, above is a set of recommendations as you are just getting started. You may find the need for other elements to be added to this file as you further develop your package and as a community begins to use your package." +msgstr "" + +#: ../../tutorials/add-readme.md:241 +msgid "In the [next lesson](add-license-coc.md), you will add a LICENSE file to your Python package. A license file is critical as it tells users how they legally can (and can't) use your package. It also:" +msgstr "" + +#: ../../tutorials/add-readme.md:245 +msgid "Builds trust with your users" +msgstr "" + +#: ../../tutorials/add-readme.md:246 +msgid "Discourages misuse of your package and associated code" +msgstr "" + +#: ../../tutorials/command-line-reference.md:1 +#: ../../tutorials/intro.md:54 +msgid "Command Line Reference Guide" +msgstr "" + +#: ../../tutorials/command-line-reference.md:4 +msgid "**What these tables are:** These tables summarize the command line inputs (e.g., `pipx install hatch`, `hatch build`) necessary to complete all steps in the package creation process, from installing Hatch to publishing the package on PyPI and conda-forge." +msgstr "" + +#: ../../tutorials/command-line-reference.md:6 +msgid "**What these tables are not:** These tables do not cover the manual/non-automated steps (e.g., create PyPI account, create PyPI API token) you have to complete throughout the package creation process." +msgstr "" + +#: ../../tutorials/command-line-reference.md:8 +msgid "**Operating system note:** The current iteration of this guide has been tested on the Windows OS only. Many commands are Windows-specific. OS-specific commands are indicated with parentheses after the description of the command, e.g., [COMMAND_DESCRIPTION] (Windows). Corresponding commands for macOS and Linux will be added in the future." +msgstr "" + +#: ../../tutorials/command-line-reference.md:11 +msgid "Environment Setup" +msgstr "" + +#: ../../tutorials/command-line-reference.md:33 +msgid "Package Development" +msgstr "" + +#: ../../tutorials/command-line-reference.md:52 +msgid "Package Publishing" +msgstr "" + +#: ../../tutorials/command-line-reference.md:71 +msgid "Versions and Environments" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:1 +msgid "Get to Know Hatch" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:3 +msgid "Our Python packaging tutorials use the tool [Hatch](https://hatch.pypa.io/latest/). While there are [many great packaging tools](/package-structure-code/python-package-build-tools) out there, we have selected Hatch because:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:8 +msgid "It is an end-to-end tool that supports most of the steps required to create a quality Python package. Beginners will have fewer tools to learn if they use Hatch." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:11 +msgid "It supports different build back-ends if you ever need to compile code in other languages." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:13 +msgid "As a community, pyOpenSci has decided that Hatch is a user-friendly tool that supports many different scientific Python use cases." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:16 +msgid "In this tutorial, you will install and get to know Hatch a bit more before starting to use it." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:19 +msgid "You need two things to successfully complete this tutorial:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:21 +msgid "You need Python installed." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:22 +msgid "You need Hatch installed." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:25 +msgid "If you don't already have Python installed on your computer, Hatch will do it for you when you install Hatch." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:29 +msgid "Install Hatch" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:31 +msgid "To begin, follow the operating-system-specific instructions below to install Hatch." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:0 +msgid "MAC" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:38 +msgid "Follow the instructions [here](https://hatch.pypa.io/latest/install/#installers)." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:40 +msgid "Download the latest GUI installer for MAC [hatch-universal.pkg](https://github.com/pypa/hatch/releases/latest/download/hatch-universal.pkg)." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:41 +msgid "Run the installer and follow the setup instructions." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:42 +msgid "If your terminal is open, then restart it." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:0 +msgid "Windows" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:48 +msgid "In your browser, download the correct `.msi` file for your system: [hatch-x64.msi](https://github.com/pypa/hatch/releases/latest/download/hatch-x64.msi)" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:50 +msgid "Run your downloaded installer file and follow the on-screen instructions." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:0 +msgid "Linux" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:56 +msgid "We suggest that you install Hatch using pipx on Linux. however, if you prefer another method, check out the [Hatch installation documentation](https://hatch.pypa.io/latest/install/) for other methods." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:70 +msgid "Hatch can also be installed directly using [pip](https://hatch.pypa.io/latest/install/#pip) or [conda](https://hatch.pypa.io/latest/install/#conda). We encourage you to follow the instructions above because we have found that the Hatch installers for Windows and Mac are the easiest and most efficient." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:74 +msgid "Our Linux users have found success installing Hatch with pipx if they already use apt install." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:77 +msgid "Both approaches (using a graphical installer on Windows/Mac and pipx) ensure that you have Hatch installed globally. A global install means that Hatch is available across all of your Python environments on your computer." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:82 +msgid "Check that hatch installed correctly" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:84 +msgid "Once you have completed the installation instructions above, you can open your terminal, and make sure that Hatch installed correctly using the command below:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:92 +msgid "*Note the version number output of `hatch --version` will likely be different from the output above in this tutorial.*" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:95 +msgid "Configure Hatch" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:97 +msgid "Once you have installed Hatch, you can customize its configuration. This includes setting the default name and setup for every package you create. While this step is not required, we suggest that you do it." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:101 +msgid "Hatch stores your configuration in a [`config.toml` file](https://hatch.pypa.io/latest/config/project-templates/)." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:103 +msgid "While you can update the `config.toml` file through the command line, it might be easier to look at and update it in a text editor if you are using it for the first time." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:107 +msgid "Step 1: Open and Edit Your `config.toml` File" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:109 +msgid "To open the config file in your file browser, run the following command in your shell:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:112 +msgid "`hatch config explore`" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:114 +msgid "This will open up a directory window that allows you to double-click on the file and open it in your favorite text editor." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:117 +msgid "You can also retrieve the location of the Hatch config file by running the following command in your shell:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:125 +msgid "Step 2 - update your email and name" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:127 +msgid "Once the file is open, update the [template] table of the `config.toml` file with your name and email. This information will be used in any `pyproject.toml` metadata files that you create using Hatch." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:137 +msgid "Step 3" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:139 +msgid "Next, set tests to false in the `[template.plugins.default]` table." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:141 +msgid "While tests are important, setting the tests configuration in Hatch to `true` will create a more complex `pyproject.toml` file. You won't need to use this feature in this beginner friendly tutorial series but we will introduce it in later tutorials." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:146 +msgid "Your `config.toml` file should look something like the one below." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:184 +msgid "Also notice that the default license option is MIT. While we will discuss license in more detail in a later lesson, the MIT license is the recommended permissive license from [choosealicense.com](https://www.choosealicense.com) and as such we will use it for this tutorial series." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:190 +msgid "You are of course welcome to select another license." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:192 +#: ../../tutorials/installable-code.md:22 +#: ../../tutorials/installable-code.md:411 +#: ../../tutorials/installable-code.md:502 +#: ../../tutorials/intro.md:235 +#: ../../tutorials/publish-pypi.md:3 +#: ../../tutorials/publish-pypi.md:178 +#: ../../tutorials/publish-pypi.md:350 +#: ../../tutorials/pyproject-toml.md:718 +msgid "Todo" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:193 +msgid "I think we'd need the SPDX license options here if they want to chose bsd-3 for instance" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:196 +msgid "Step 4: Close the config file and run `hatch config show`" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:198 +msgid "Once you have completed the steps above run the following command in your shell." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:200 +msgid "`hatch config show`" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:202 +msgid "`hatch config show` will print out the contents of your `config.toml` file in your shell. Look at the values and ensure that your name, email is set. Also make sure that `tests=false`." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:206 +msgid "Hatch features" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:208 +msgid "Hatch offers a suite of features that will make creating, publishing and maintaining your Python package easier." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:211 +msgid "Comparison to other tools" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:213 +msgid "[We compared Hatch to several of the other popular packaging tools in the ecosystem including flit, pdm and poetry. Learn more here](package-features)" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:216 +msgid "[More on Hatch here](hatch)" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:218 +msgid "A few features that Hatch offers" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:220 +msgid "It will convert metadata stored in a `setup.py` or `setup.cfg` file to a pyproject.toml file for you (see [Migrating setup.py to pyproject.toml using Hatch](setup-py-to-pyproject-toml.md ))" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:222 +msgid "It will help you by storing configuration information for publishing to PyPI after you've entered it once." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:224 +msgid "Use `hatch -h` to see all of the available commands." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:226 +msgid "What's next" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:228 +msgid "In the next lesson you'll learn how to package and make your code installable using Hatch." +msgstr "" + +#: ../../tutorials/installable-code.md:6 +msgid "Make your Python code installable" +msgstr "" + +#: ../../tutorials/installable-code.md:8 +msgid "What we previously covered" +msgstr "" + +#: ../../tutorials/installable-code.md:9 +msgid "[In the previous lesson](intro), you learned about what a Python package is. You also learned about the [benefits of creating a Python package](package-benefits)." +msgstr "" + +#: ../../tutorials/installable-code.md:13 +msgid "Your next step in our packaging tutorial series is to create a Python package that is installable both locally and remotely from a website such as GitHub (or GitLab). The package that you create in this lesson will have the bare minimum elements needed to be installable into a Python environment." +msgstr "" + +#: ../../tutorials/installable-code.md:18 +msgid "Making your code installable is an important steps towards creating a full Python package that is directly installable from PyPI." +msgstr "" + +#: ../../tutorials/installable-code.md:23 +msgid "Is it clear where to add commands? Bash vs. Python console Bash vs. Zsh is different" +msgstr "" + +#: ../../tutorials/installable-code.md:25 +msgid "Does this lesson run as expected on windows and mac?" +msgstr "" + +#: ../../tutorials/installable-code.md:26 +msgid "ADD: note about what makes something \"package worthy\", with a common misconception being that a package should be production-ready code that's valuable to a broad audience. This may not be a pervasive misconception in Python, but a quick break-out with an explanation of what a package can consist of would be helpful." +msgstr "" + +#: ../../tutorials/installable-code.md:31 +msgid "Diagram showing the basic steps to creating an installable package. There are 4 boxes with arrows pointing towards the right. The boxes read, your code, create package structure, add metadata to pyproject.toml and pip install package." +msgstr "" + +#: ../../tutorials/installable-code.md:33 +msgid "A basic installable package needs a few things: code, a [specific package file structure](https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-structure.html) and a `pyproject.toml` containing your package's name and version. Once you have these items in the correct directory structure, you can pip install your package into any environment on your computer. You will learn how to create a basic installable package in this lesson." +msgstr "" + +#: ../../tutorials/installable-code.md:37 +msgid "About this lesson" +msgstr "" + +#: ../../tutorials/installable-code.md:43 +msgid "How to make your code installable into any Python environment both locally and from GitHub" +msgstr "" + +#: ../../tutorials/installable-code.md:44 +msgid "How to create a basic `pyproject.toml` file that includes package dependencies and metadata. This file is required to make your package installable." +msgstr "" + +#: ../../tutorials/installable-code.md:45 +msgid "How to declare a [build backend](build_backends) which will be used to [build](build-package) and install your package" +msgstr "" + +#: ../../tutorials/installable-code.md:46 +msgid "How to install your package in editable mode for interactive development" +msgstr "" + +#: ../../tutorials/installable-code.md:48 +msgid "**What you need to complete this lesson**" +msgstr "" + +#: ../../tutorials/installable-code.md:50 +msgid "To complete this lesson you will need a local Python environment and shell on your computer. You will also need to have [Hatch installed](get-to-know-hatch)." +msgstr "" + +#: ../../tutorials/installable-code.md:53 +msgid "If you are using Windows or are not familiar with Shell, you may want to check out the Carpentries shell lesson[^shell-lesson]. Windows users will likely need to configure a tool for any Shell and git related steps." +msgstr "" + +#: ../../tutorials/installable-code.md:55 +msgid "**What comes next**" +msgstr "" + +#: ../../tutorials/installable-code.md:57 +msgid "In the upcoming lessons you will learn how to:" +msgstr "" + +#: ../../tutorials/installable-code.md:59 +msgid "[Publish your package to PyPI](publish-pypi)" +msgstr "" + +#: ../../tutorials/installable-code.md:60 +msgid "Add a README file to your package to support community use" +msgstr "" + +#: ../../tutorials/installable-code.md:61 +msgid "Add additional project metadata to your package to support PyPI publication" +msgstr "" + +#: ../../tutorials/installable-code.md:67 +msgid "This diagram has two smaller boxes with arrows pointing to the right to a Python environment. The small boxes read your-package and pip install package. The environment box on the right reads - your Python environment. It them lists your-package along with a few other core packages such as Matplotlib, NumPy, Pandas, Xarray and GeoPandas." +msgstr "" + +#: ../../tutorials/installable-code.md:69 +msgid "Making your code installable is the first step towards creating a publishable Python package. Once your code is installable, it is a Python package and can be added to any Python environment on your computer and imported in the same way that you might import a package such as Pandas or GeoPandas. If your code is on GitHub or GitLab you can also install it directly from there." +msgstr "" + +#: ../../tutorials/installable-code.md:74 +msgid "About the Python package directory structure" +msgstr "" + +#: ../../tutorials/installable-code.md:76 +msgid "To make your Python code installable you need to create a specific directory structure with the following elements:" +msgstr "" + +#: ../../tutorials/installable-code.md:78 +msgid "A `pyproject.toml` file." +msgstr "" + +#: ../../tutorials/installable-code.md:79 +msgid "A specific directory structure." +msgstr "" + +#: ../../tutorials/installable-code.md:80 +msgid "Some code." +msgstr "" + +#: ../../tutorials/installable-code.md:81 +msgid "An `__init__.py` file in your code directory." +msgstr "" + +#: ../../tutorials/installable-code.md:83 +msgid "The directory structure you'll create in this lesson will look like this:" +msgstr "" + +#: ../../tutorials/installable-code.md:95 +msgid "About the basic package directory structure" +msgstr "" + +#: ../../tutorials/installable-code.md:97 +msgid "Notice a few things about the above layout:" +msgstr "" + +#: ../../tutorials/installable-code.md:99 +msgid "Your package code lives within a `src/packagename` directory. We suggest that you use `src` (short for **source code**) directory as it [ensures that you are running tests on the installed version of your code](https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-structure.html#the-src-layout-and-testing)." +msgstr "" + +#: ../../tutorials/installable-code.md:100 +msgid "Within the `src` directory you have a package directory called `pyospackage`. Use the name of your package for that directory name. This will be the name for importing your package in Python code once installed." +msgstr "" + +#: ../../tutorials/installable-code.md:101 +msgid "In your package directory, you have an `__init__.py` file and all of your Python modules. You will learn more about the `__init__.py` file below." +msgstr "" + +#: ../../tutorials/installable-code.md:102 +msgid "The `pyproject.toml` file lives at the root directory of your package." +msgstr "" + +#: ../../tutorials/installable-code.md:103 +msgid "The name of the root directory for the package is **pyospackage** which is the name of the package. This is not a requirement but you will often see that the GitHub / GitLab repository and the root directory name are the same as the package name." +msgstr "" + +#: ../../tutorials/installable-code.md:105 +msgid "What is an `__init__.py` file?" +msgstr "" + +#: ../../tutorials/installable-code.md:107 +msgid "The `__init__.py` file tells Python that a directory should be treated as a Python package. As such, a directory with an `__init__.py` file can be imported directly into Python. The `__init__.py` file does not need to contain any code in order for Python to recognize it; it can be empty." +msgstr "" + +#: ../../tutorials/installable-code.md:111 +msgid "For example, following the file structure example above which has an `__init__.py` file within it, you can run:" +msgstr "" + +#: ../../tutorials/installable-code.md:117 +#: ../../tutorials/pyproject-toml.md:48 +msgid "What is a pyproject.toml file?" +msgstr "" + +#: ../../tutorials/installable-code.md:119 +msgid "The **pyproject.toml** file is:" +msgstr "" + +#: ../../tutorials/installable-code.md:121 +msgid "Where you define your project's metadata (including its name, authors, license, etc)" +msgstr "" + +#: ../../tutorials/installable-code.md:122 +msgid "Where you define dependencies (the packages that it depends on)" +msgstr "" + +#: ../../tutorials/installable-code.md:123 +msgid "Used to specify and configure what build backend you want to use to [build your package](../package-structure-code/python-package-distribution-files-sdist-wheel)." +msgstr "" + +#: ../../tutorials/installable-code.md:125 +msgid "After the `__init__.py` and `pyproject.toml` files have been added, your package can be built and distributed as an installable Python package using tools such as pip. Note that the `pyproject.toml` file needs to have a few basic items defined for the package to be installable including:" +msgstr "" + +#: ../../tutorials/installable-code.md:131 +msgid "The `build-backend` that you want to use," +msgstr "" + +#: ../../tutorials/installable-code.md:132 +msgid "The project `name` and `version`." +msgstr "" + +#: ../../tutorials/installable-code.md:134 +msgid "Why the pyproject.toml file is important" +msgstr "" + +#: ../../tutorials/installable-code.md:138 +msgid "The `pyproject.toml` file replaces some of the functionality of both the `setup.py` file and `setup.cfg` files. If you try to pip install a package with no `pyproject.toml` you will get the following error:" +msgstr "" + +#: ../../tutorials/installable-code.md:150 +msgid "Note about `setup.py`" +msgstr "" + +#: ../../tutorials/installable-code.md:154 +msgid "If your project already defines a `setup.py` file, Hatch can be used to automatically create the `pyproject.toml`." +msgstr "" + +#: ../../tutorials/installable-code.md:155 +msgid "See [Using Hatch to Migrate setup.py to a pyproject.toml ](setup-py-to-pyproject-toml.md)" +msgstr "" + +#: ../../tutorials/installable-code.md:161 +msgid "Time to create your Python package!" +msgstr "" + +#: ../../tutorials/installable-code.md:163 +msgid "Now that you understand the basics of the Python package directory structure, and associated key files (`__init__.py` and `pyproject.toml`), it's time to create your Python package! Below you will create a directory structure similar to the structure described above using Hatch." +msgstr "" + +#: ../../tutorials/installable-code.md:167 +msgid "Step 1: Set Up the Package Directory Structure" +msgstr "" + +#: ../../tutorials/installable-code.md:169 +msgid "Open your shell or preferred terminal." +msgstr "" + +#: ../../tutorials/installable-code.md:170 +msgid "Use the shell `cd` command to navigate in your shell to the location where you'd like your package directory to live. Hatch will create the package directory for you" +msgstr "" + +#: ../../tutorials/installable-code.md:171 +msgid "Choose a name for your package. The name should:" +msgstr "" + +#: ../../tutorials/installable-code.md:172 +msgid "Have no spaces (*Required*)" +msgstr "" + +#: ../../tutorials/installable-code.md:173 +msgid "Use all lowercase characters (*Recommended*). For this tutorial we will use `pyospackage`." +msgstr "" + +#: ../../tutorials/installable-code.md:174 +msgid "Only use letter and the characters _ or - in the name. This means that the name `pyos*package` is not an acceptable name. However, the names `pyos_package` or `pyos-package` both are ok" +msgstr "" + +#: ../../tutorials/installable-code.md:176 +msgid "Hatch and project names" +msgstr "" + +#: ../../tutorials/installable-code.md:177 +msgid "Hatch makes some decisions for your project's name when you run `hatch new`" +msgstr "" + +#: ../../tutorials/installable-code.md:179 +msgid "These include using:" +msgstr "" + +#: ../../tutorials/installable-code.md:180 +msgid "dashes for the top level directory" +msgstr "" + +#: ../../tutorials/installable-code.md:181 +msgid "dashes for the project name in the pyproject.toml" +msgstr "" + +#: ../../tutorials/installable-code.md:182 +msgid "underscores for the package directory name" +msgstr "" + +#: ../../tutorials/installable-code.md:196 +msgid "If you use a name with underscores, Hatch will return the same thing:" +msgstr "" + +#: ../../tutorials/installable-code.md:209 +msgid "In both of the examples above the project name in the pyproject.toml file that hatch creates is `pyos-package`." +msgstr "" + +#: ../../tutorials/installable-code.md:213 +msgid "Next run:" +msgstr "" + +#: ../../tutorials/installable-code.md:228 +msgid "Your final project directory structure should look like this:" +msgstr "" + +#: ../../tutorials/installable-code.md:243 +msgid "Step 2: Add module to your package" +msgstr "" + +#: ../../tutorials/installable-code.md:245 +msgid "A Python module refers to a `.py` file containing the code that you want your package to access and run. Within the `pyospackage` subdirectory, add at least one Python modules (.py files)." +msgstr "" + +#: ../../tutorials/installable-code.md:247 +msgid "If you don't have code already and are just learning how to create a Python package, then create an empty `add_numbers.py` file. You will populate the `add_numbers.py` file with code provided below." +msgstr "" + +#: ../../tutorials/installable-code.md:250 +msgid "Python modules and the `__init__.py` file" +msgstr "" + +#: ../../tutorials/installable-code.md:254 +msgid "When you see the word module, we are referring to a `.py` file containing Python code." +msgstr "" + +#: ../../tutorials/installable-code.md:257 +msgid "The `__init__.py` allows Python to recognize that a directory contains at least one module that may be imported and used in your code. A package can have multiple modules[^python-modules]." +msgstr "" + +#: ../../tutorials/installable-code.md:261 +msgid "Your project directory should now look like this:" +msgstr "" + +#: ../../tutorials/installable-code.md:271 +msgid "Step 3: Add code to your module" +msgstr "" + +#: ../../tutorials/installable-code.md:273 +msgid "If you are following along and making a Python package from scratch then you can add the code below to your `add_numbers.py` module. The function below adds two integers together and returns the result. Notice that the code below has a few features that we will review in future tutorials:" +msgstr "" + +#: ../../tutorials/installable-code.md:275 +msgid "It has a [numpy-style docstring](numpy-docstring)" +msgstr "" + +#: ../../tutorials/installable-code.md:276 +msgid "It uses [typing](type-hints)" +msgstr "" + +#: ../../tutorials/installable-code.md:278 +msgid "Python can support many different docstrings formats depending on the documentation build system you wish to use. The most popular supported formats for documenting Python objects are NumPy Style Docstring[^numpydoc], Google Style Docstring[^googledoc], and the Epytext Style Docstrings[^epytextdoc]." +msgstr "" + +#: ../../tutorials/installable-code.md:280 +msgid "**pyOpenSci recommends using the NumPy Docstring convention.**" +msgstr "" + +#: ../../tutorials/installable-code.md:282 +msgid "If you aren't familiar with docstrings or typing yet, that is ok. You can review [this page in the pyOpenSci packaging guide](https://www.pyopensci.org/python-package-guide/documentation/write-user-documentation/document-your-code-api-docstrings.html) for an overview of both topics." +msgstr "" + +#: ../../tutorials/installable-code.md:311 +msgid "Step 4: Modify metadata in your `pyproject.toml` file" +msgstr "" + +#: ../../tutorials/installable-code.md:313 +msgid "Next, you will modify some of the metadata (information) that Hatch adds to your `pyproject.toml` file. You are are welcome to copy the file we have in our [example pyospackage GitHub repository](https://github.com/pyOpenSci/pyosPackage)." +msgstr "" + +#: ../../tutorials/installable-code.md:317 +msgid "Brief overview of the TOML file" +msgstr "" + +#: ../../tutorials/installable-code.md:320 +msgid "[The TOML format](https://toml.io/en/) consists of tables and variables. Tables are sections of information denoted by square brackets:" +msgstr "" + +#: ../../tutorials/installable-code.md:322 +msgid "`[this-is-a-table]`." +msgstr "" + +#: ../../tutorials/installable-code.md:324 +msgid "Tables can contain variables within them defined by an variable name and an `=` sign. For instance, a `build-system` table most often holds two (2) variables:" +msgstr "" + +#: ../../tutorials/installable-code.md:327 +msgid "`requires = `, which tells a build tool what tools it needs to install prior to building your package. In this case [hatchling](https://pypi.org/project/hatchling/)" +msgstr "" + +#: ../../tutorials/installable-code.md:329 +msgid "`build-backend = `, which is used to define the specific build-backend name, (in this example we are using `hatchling.build`)." +msgstr "" + +#: ../../tutorials/installable-code.md:338 +msgid "TOML organizes data structures, defining relationships within a configuration file." +msgstr "" + +#: ../../tutorials/installable-code.md:341 +msgid "[Learn more about the pyproject.toml format here.](../package-structure-code/pyproject-toml-python-package-metadata)" +msgstr "" + +#: ../../tutorials/installable-code.md:345 +msgid "You will learn more about the `pyproject.toml` format in the [next lesson when you add additional metadata / information to this file.](pyproject-toml.md)" +msgstr "" + +#: ../../tutorials/installable-code.md:348 +msgid "Open up the `pyproject.toml` file that Hatch created in your favorite text editor. It should look something like the example below." +msgstr "" + +#: ../../tutorials/installable-code.md:390 +msgid "Edit the file as follows:" +msgstr "" + +#: ../../tutorials/installable-code.md:392 +msgid "Delete `dynamic = [\"version\"]`: This sets up dynamic versioning based on tags stored in your git commit history. We will walk through implementing this in a later lesson." +msgstr "" + +#: ../../tutorials/installable-code.md:393 +msgid "Add `version = \"0.1\"` in the place of `dynamic = [\"version\"]` which you just deleted. This sets up manual versioning." +msgstr "" + +#: ../../tutorials/installable-code.md:394 +msgid "Fill in the description if it doesn't already exist." +msgstr "" + +#: ../../tutorials/installable-code.md:404 +msgid "Remove the `[tool.hatch.version]` table from the bottom of the file." +msgstr "" + +#: ../../tutorials/installable-code.md:412 +msgid "When this lesson exists, uncomment this admonition You will learn how to automate defining a package version using git tags in the version and release your package lesson." +msgstr "" + +#: ../../tutorials/installable-code.md:417 +msgid "OPTIONAL: Adjust project classifiers" +msgstr "" + +#: ../../tutorials/installable-code.md:419 +msgid "Hatch by default provides a list of classifiers that define what Python versions your package supports. These classifiers do not in any way impact your package's build and are primarily intended to be used when you publish your package to PyPI." +msgstr "" + +#: ../../tutorials/installable-code.md:424 +msgid "If you don't plan on publishing to PyPI, you can skip this section. However, if you wish, you can clean it up a bit." +msgstr "" + +#: ../../tutorials/installable-code.md:427 +msgid "To begin:" +msgstr "" + +#: ../../tutorials/installable-code.md:429 +msgid "Remove support for Python 3.8" +msgstr "" + +#: ../../tutorials/installable-code.md:430 +msgid "Within the `[project]` table, update `requires-python = \">3.8\"` to `requires-python = \">3.9\"`" +msgstr "" + +#: ../../tutorials/installable-code.md:432 +msgid "Since you are creating a pure Python package in this lesson, you can remove the following classifiers:" +msgstr "" + +#: ../../tutorials/installable-code.md:442 +msgid "Your new pyproject.toml file should now look something like this:" +msgstr "" + +#: ../../tutorials/installable-code.md:477 +msgid "The bare minimum needed in a pyproject.toml file" +msgstr "" + +#: ../../tutorials/installable-code.md:480 +msgid "The core information that you need in a `pyproject.toml` file in order to publish on PyPI is your **package's name** and the **version**. However, we suggest that you flesh out your metadata early on in the `pyproject.toml` file." +msgstr "" + +#: ../../tutorials/installable-code.md:482 +msgid "Once you have your project metadata in the pyproject.toml file, you will rarely update it. In the next lesson you'll add more metadata and structure to this file." +msgstr "" + +#: ../../tutorials/installable-code.md:486 +msgid "Step 5: Install your package locally" +msgstr "" + +#: ../../tutorials/installable-code.md:488 +msgid "At this point you should have:" +msgstr "" + +#: ../../tutorials/installable-code.md:490 +msgid "A project directory structure with a `pyproject.toml` file at the root" +msgstr "" + +#: ../../tutorials/installable-code.md:491 +msgid "A package directory containing an empty `__init__.py` file and" +msgstr "" + +#: ../../tutorials/installable-code.md:492 +msgid "At least one Python module (e.g. `add_numbers.py`)" +msgstr "" + +#: ../../tutorials/installable-code.md:494 +msgid "You are now ready to install (and build) your Python package!" +msgstr "" + +#: ../../tutorials/installable-code.md:496 +msgid "While you can do this using hatch, we are going to use pip for this lesson, so you can see how to install your tool into your preferred environment." +msgstr "" + +#: ../../tutorials/installable-code.md:498 +msgid "First open your preferred shell (Windows users may be using something like gitbash) and `cd` into your project directory if you are not already there." +msgstr "" + +#: ../../tutorials/installable-code.md:499 +msgid "Activate the Python environment that you wish to use." +msgstr "" + +#: ../../tutorials/installable-code.md:500 +msgid "Run `python -m pip install -e .`" +msgstr "" + +#: ../../tutorials/installable-code.md:503 +msgid "Add this back in when the lesson is published" +msgstr "" + +#: ../../tutorials/installable-code.md:504 +msgid "Activate the Python environment that you wish to use. If you need help with working with virtual environments check out this lesson (add link)." +msgstr "" + +#: ../../tutorials/installable-code.md:530 +msgid "What does `python -m pip install -e .` do?" +msgstr "" + +#: ../../tutorials/installable-code.md:533 +msgid "Let's break down `python -m pip install -e .`" +msgstr "" + +#: ../../tutorials/installable-code.md:535 +msgid "`python -m pip install -e .` installs your package into the current active Python environment in **editable mode** (`-e`). Installing your package in editable mode, allows you to work on your code and then test the updates interactively in your favorite Python interface. One important caveat of editable mode is that every time you update your code, you may need to restart Python." +msgstr "" + +#: ../../tutorials/installable-code.md:540 +msgid "If you wish to install the package regularly (not in editable mode) you can use:" +msgstr "" + +#: ../../tutorials/installable-code.md:543 +msgid "`python -m pip install . `" +msgstr "" + +#: ../../tutorials/installable-code.md:545 +msgid "**Using `python -m` when calling `pip`**" +msgstr "" + +#: ../../tutorials/installable-code.md:547 +msgid "Above, you use`python -m` to call the version of pip installed into your current active environment. `python -m` is important to ensure that you are calling the version of pip installed in your current environment." +msgstr "" + +#: ../../tutorials/installable-code.md:552 +msgid "Look for pyospackage in your environment" +msgstr "" + +#: ../../tutorials/installable-code.md:554 +msgid "Once you have installed your package, you can view it in your current environment. If you are using `venv` or `conda`, `pip` list will allow you to see your current package installations." +msgstr "" + +#: ../../tutorials/installable-code.md:558 +msgid "Note that because pyospackage is installed in editable mode (`-e`) pip will show you the directory path to your project's code" +msgstr "" + +#: ../../tutorials/installable-code.md:586 +msgid "Step 6: Test out your new package" +msgstr "" + +#: ../../tutorials/installable-code.md:588 +msgid "After installing your package, type “python” at the command prompt in your chosen terminal to start a Python session in your active Python environment." +msgstr "" + +#: ../../tutorials/installable-code.md:591 +msgid "You can now import your package and access the `add_num` function." +msgstr "" + +#: ../../tutorials/installable-code.md:603 +msgid "Installing packages from GitHub" +msgstr "" + +#: ../../tutorials/installable-code.md:605 +msgid "If you wish to share your code without publishing to PyPI you can always install packages directly from GitHub using the syntax:" +msgstr "" + +#: ../../tutorials/installable-code.md:612 +msgid "To make your package GitHub installable, you can:" +msgstr "" + +#: ../../tutorials/installable-code.md:614 +msgid "Create a new GitHub repository" +msgstr "" + +#: ../../tutorials/installable-code.md:615 +msgid "Push the contents of the project directory that you created above, to GitHub" +msgstr "" + +#: ../../tutorials/installable-code.md:616 +msgid "Finally install the package from GitHub using the command above. When you use the command above, don't forget to substitute the user, repo, and branch_or_tag with your specific values." +msgstr "" + +#: ../../tutorials/installable-code.md:618 +msgid "For instance below you install the pyospackage from the main branch of the pyOpenSci repository." +msgstr "" + +#: ../../tutorials/installable-code.md:621 +msgid "`python -m pip install git+https://github.com/user/repo.git@branch_or_tag`" +msgstr "" + +#: ../../tutorials/installable-code.md:625 +msgid "Congratulations! You created your first Python package" +msgstr "" + +#: ../../tutorials/installable-code.md:627 +msgid "You did it! You have now created a Python package that you can install into any Python environment." +msgstr "" + +#: ../../tutorials/installable-code.md:630 +msgid "In the upcoming lessons you will:" +msgstr "" + +#: ../../tutorials/installable-code.md:632 +msgid "Learn how to [build and publish your Python package to (test) PyPI](publish-pypi)" +msgstr "" + +#: ../../tutorials/installable-code.md:633 +msgid "Add a README file and LICENSE to your package" +msgstr "" + +#: ../../tutorials/installable-code.md:634 +msgid "Add more metadata to your `pyproject.toml` file to support PyPI publication." +msgstr "" + +#: ../../tutorials/installable-code.md:635 +msgid "learn how to publish to **conda-forge** from **PyPI**." +msgstr "" + +#: ../../tutorials/installable-code.md:637 +msgid "Add a [README file](add-readme.md) and [LICENSE](add-license-coc.md) to your package" +msgstr "" + +#: ../../tutorials/installable-code.md:638 +msgid "[Add more metadata to your `pyproject.toml`](pyproject-toml.md) file to support PyPI publication." +msgstr "" + +#: ../../tutorials/installable-code.md:639 +msgid "[Learn how to build your package distribution](publish-pypi) files (**sdist** and **wheel**) and publish to **test PyPI**." +msgstr "" + +#: ../../tutorials/installable-code.md:640 +msgid "Finally you will learn how to [publish to **conda-forge**](publish-conda-forge) from **PyPI**." +msgstr "" + +#: ../../tutorials/installable-code.md:644 +msgid "[Carpentries shell lesson](https://swcarpentry.github.io/shell-novice/)" +msgstr "" + +#: ../../tutorials/installable-code.md:646 +msgid "[Python module docs](https://docs.python.org/3/tutorial/modules.html#packages)" +msgstr "" + +#: ../../tutorials/installable-code.md:648 +msgid "[Numpy style docs](https://numpydoc.readthedocs.io/en/latest/format.html)" +msgstr "" + +#: ../../tutorials/installable-code.md:647 +msgid "[Google docstring style](https://google.github.io/styleguide/pyguide.html)" +msgstr "" + +#: ../../tutorials/installable-code.md:649 +msgid "[epydoc](https://epydoc.sourceforge.net/epytext.html)" +msgstr "" + +#: ../../tutorials/intro.md:28 +#: ../../tutorials/setup-py-to-pyproject-toml.md:24 +msgid "Get to know Hatch" +msgstr "" + +#: ../../tutorials/intro.md:28 +msgid "Python Packaging Tutorial Setup" +msgstr "" + +#: ../../tutorials/intro.md:35 +#: ../../tutorials/intro.md:80 +msgid "What is a Python package?" +msgstr "" + +#: ../../tutorials/intro.md:35 +msgid "Create a Python package" +msgstr "" + +#: ../../tutorials/intro.md:35 +msgid "Publish to PyPI" +msgstr "" + +#: ../../tutorials/intro.md:35 +msgid "Publish to conda-forge" +msgstr "" + +#: ../../tutorials/intro.md:35 +msgid "Create and publish a Python Package" +msgstr "" + +#: ../../tutorials/intro.md:45 +msgid "Add README file" +msgstr "" + +#: ../../tutorials/intro.md:45 +msgid "Add a license & code of conduct" +msgstr "" + +#: ../../tutorials/intro.md:45 +msgid "Update metadata in pyproject.toml" +msgstr "" + +#: ../../tutorials/intro.md:45 +msgid "Project information files & metadata" +msgstr "" + +#: ../../tutorials/intro.md:54 +msgid "Reference Guides" +msgstr "" + +#: ../../tutorials/intro.md:61 +msgid "Migrate setup.py to a pyproject.toml using Hatch" +msgstr "" + +#: ../../tutorials/intro.md:61 +msgid "Hatch for Existing Packages" +msgstr "" + +#: ../../tutorials/intro.md:2 +msgid "Python packaging 101" +msgstr "" + +#: ../../tutorials/intro.md:4 +msgid "_A start to finish beginner-friendly tutorial_" +msgstr "" + +#: ../../tutorials/intro.md:6 +msgid "Welcome to the pyOpenSci Python packaging tutorial series. The lessons on the upcoming pages walk you through the core steps needed to create a Python package." +msgstr "" + +#: ../../tutorials/intro.md:12 +msgid "Diagram showing the lessons in our packaging tutorial. There are 6 total - what is a Python package, make code pip installable, publish your package to PyPI, add a README and LICENSE file, add metadata for PyPI and finally publish to conda forge." +msgstr "" + +#: ../../tutorials/intro.md:14 +msgid "This lesson is the first in a series of lessons to help you get started with Python packaging." +msgstr "" + +#: ../../tutorials/intro.md:17 +msgid "Who are these tutorials for?" +msgstr "" + +#: ../../tutorials/intro.md:19 +msgid "The content in this tutorial series is beginner friendly and assumes that you have not created a Python package before. However, the content will still be valuable if you are interested in better understanding the steps involved in creating a Python package." +msgstr "" + +#: ../../tutorials/intro.md:24 +msgid "In this series you will learn about the core elements that you need to publish your package to the [Python Package Index (PyPI)](https://pypi.org/)." +msgstr "" + +#: ../../tutorials/intro.md:26 +msgid "In the second series, you will learn about infrastructure and documentation needed to support package maintenance." +msgstr "" + +#: ../../tutorials/intro.md:68 +#: ../../tutorials/publish-conda-forge.md:15 +#: ../../tutorials/publish-pypi.md:13 +#: ../../tutorials/pyproject-toml.md:19 +#: ../../tutorials/setup-py-to-pyproject-toml.md:12 +msgid "Learning Objectives" +msgstr "" + +#: ../../tutorials/intro.md:70 +msgid "This lesson introduces you to the basic components of a Python package. After reading this lesson you will:" +msgstr "" + +#: ../../tutorials/intro.md:73 +msgid "Understand what a Python package is" +msgstr "" + +#: ../../tutorials/intro.md:74 +msgid "Be able to list the 5 core components of a Python package" +msgstr "" + +#: ../../tutorials/intro.md:75 +msgid "Be able to explain the difference between generalizable code and code that supports a specific scientific application" +msgstr "" + +#: ../../tutorials/intro.md:82 +msgid "At a high level, you can think about a Python package as a toolbox that you can use to perform various tasks." +msgstr "" + +#: ../../tutorials/intro.md:85 +msgid "A Python package is basically a directory with a specific file structure. Within the package directory structure, there are modules which are files that end in `.py` (the same extension you'd see in a Python script). These modules allow you to group and structure your Python code. Each module contains functions and classes, that you can think about as the tools in your toolbox." +msgstr "" + +#: ../../tutorials/intro.md:94 +msgid "Diagram showing a sketch of a toolbox filled with different tools including a hammer and a saw." +msgstr "" + +#: ../../tutorials/intro.md:96 +msgid "You can think about a package as a toolbox filled with coding tools. A tool may be a function or a class. Each tool does a specific thing well." +msgstr "" + +#: ../../tutorials/intro.md:101 +msgid "Python packages are installable" +msgstr "" + +#: ../../tutorials/intro.md:103 +msgid "A package is installable, which means that you can add the functionality within the package's code to any Python environment and import that functionality like you would import core scientific Python packages such as NumPy or Matplotlib." +msgstr "" + +#: ../../tutorials/intro.md:112 +msgid "Installing a package into an environment makes it easier to manage and reuse your code across different projects. Structuring your code as a package is the first step you need to take so you can share the tools in the toolbox you've created and let others build with it." +msgstr "" + +#: ../../tutorials/intro.md:117 +msgid "Why create a Python package?" +msgstr "" + +#: ../../tutorials/intro.md:119 +msgid "You might create a Python package because you want to:" +msgstr "" + +#: ../../tutorials/intro.md:121 +msgid "**Use your code across different projects:** At its most basic level, creating a package allows you to install your code into a Python environment. This allows you to then import functions and classes into any workflows both locally and in the cloud." +msgstr "" + +#: ../../tutorials/intro.md:122 +msgid "**Share your code:** If you publish a package on a public repository such as PyPI or conda, your package can be installed on any machine using pip or conda with a single command." +msgstr "" + +#: ../../tutorials/intro.md:123 +msgid "**Build community around your code:** Packages make it easier for multiple people to work on the same project (particularly when published on GitHub). A version control system such as git (the system used by GitHub), further makes it easier to track changes to the codebase over time. Tools such as issues and pull requests make it easier for outside users to contribute bug fixes and to establish review processes for accepting changes to the code base." +msgstr "" + +#: ../../tutorials/intro.md:124 +msgid "**Organize your code:** Packages can be used to organize large code projects, dividing them into smaller, more manageable components. This structure can help with both maintaining the codebase and with making it easier to understand." +msgstr "" + +#: ../../tutorials/intro.md:126 +msgid "What to consider before you create a package" +msgstr "" + +#: ../../tutorials/intro.md:128 +msgid "Creating a Python package that others use takes considerable time and effort. Before you begin, think about your goals including:" +msgstr "" + +#: ../../tutorials/intro.md:131 +msgid "Who you think will use your package" +msgstr "" + +#: ../../tutorials/intro.md:132 +msgid "How people might use your package and on what data (if data are relevant)" +msgstr "" + +#: ../../tutorials/intro.md:133 +msgid "Whether you have time to add things such as documentation and tests" +msgstr "" + +#: ../../tutorials/intro.md:134 +msgid "How long you might be able to maintain it: remember that once people begin using your package they will depend on your maintainer team to update it, fix bugs and answer questions." +msgstr "" + +#: ../../tutorials/intro.md:136 +msgid "Before creating a user-facing package, it's important to consider all of the above." +msgstr "" + +#: ../../tutorials/intro.md:138 +msgid "The elements of a Python package" +msgstr "" + +#: ../../tutorials/intro.md:142 +#: ../../tutorials/intro.md:220 +msgid "Diagram showing .. more here if this stays." +msgstr "" + +#: ../../tutorials/intro.md:144 +msgid "The elements of a Python package include code, documentation, tests, an OSI-approved license and infrastructure. Maintainers are at the core making sure everything works and is up to date while fixing bugs and addressing user concerns." +msgstr "" + +#: ../../tutorials/intro.md:150 +msgid "The core elements of Python package include:" +msgstr "" + +#: ../../tutorials/intro.md:152 +msgid "**Code:** Functions and classes that provide functionality for a user of your package" +msgstr "" + +#: ../../tutorials/intro.md:153 +msgid "**Documentation:** Installation instructions, tutorials, and examples that both help users get started using your package and contributors and maintainers fix bugs and maintain the package." +msgstr "" + +#: ../../tutorials/intro.md:154 +msgid "Contributor Documentation in the form of a **CONTRIBUTING.md** file is useful to help people to contribute to your package." +msgstr "" + +#: ../../tutorials/intro.md:155 +msgid "Development Documentation helps both maintainers and contributors understand how to maintain a package's infrastructure." +msgstr "" + +#: ../../tutorials/intro.md:156 +msgid "**Tests:** that make sure your code works as it should and makes it easier for you and others to contribute to, modify and update the code in the future" +msgstr "" + +#: ../../tutorials/intro.md:157 +msgid "**License:** An open source license, or license that is [OSI approved](https://opensource.org/licenses/), refers to an license that allows others to use your package. It also provides legal direction regarding how elements of the package can and can't be reused." +msgstr "" + +#: ../../tutorials/intro.md:158 +msgid "**Infrastructure** that automates updates, publication workflows and runs test suites. Infrastructure includes a suite of things such as platforms like GitHub and GitLab, tools to run tests and tools locally such as nox and tox and continuous integration that automates package maintenance steps." +msgstr "" + +#: ../../tutorials/intro.md:160 +msgid "What pyOpenSci looks for in a package" +msgstr "" + +#: ../../tutorials/intro.md:163 +msgid "pyOpenSci performs an [initial set of editor checks](https://www.pyopensci.org/software-peer-review/how-to/editor-in-chief-guide.html#editor-checklist-template) for any package submitted to us for peer review. You may find these checks useful as you create your package as a baseline for things that you package should have." +msgstr "" + +#: ../../tutorials/intro.md:169 +msgid "Packages are more than just code - Infrastructure" +msgstr "" + +#: ../../tutorials/intro.md:171 +msgid "A package in any language is more than just code. If you expect other people to use your package, besides yourself, you should consider not only writing high quality code, but also the various elements of a package that make it a useful community resource." +msgstr "" + +#: ../../tutorials/intro.md:176 +msgid "Version control and storing your package on GitHub or GitLab" +msgstr "" + +#: ../../tutorials/intro.md:178 +msgid "Most Python packages live in an online version control platform such as GitHub or GitLab. GitHub and GitLab both run [git](https://git-scm.com/) for version control. Having your software under version control is important because it allows you to both track changes over time while also going back in history and undoing changes in the case that a change to the code base unexpectedly breaks something." +msgstr "" + +#: ../../tutorials/intro.md:183 +msgid "By publishing your package on GitHub or GitLab, you are making your code public facing. This means that others can both see your code and also make contributions using a pull request (GitHub) / merge request (GitLab) / code review workflow." +msgstr "" + +#: ../../tutorials/intro.md:185 +msgid "GitHub & GitLab vs. Git" +msgstr "" + +#: ../../tutorials/intro.md:188 +msgid "GitHub and GitLab are online (cloud) platforms that run `git` (version control software) on the backend. Running git locally on your computer allows you to upload (`git push`) and download (`git pull`) files to GitHub and GitLab." +msgstr "" + +#: ../../tutorials/intro.md:193 +msgid "Issues or Ticket Trackers" +msgstr "" + +#: ../../tutorials/intro.md:195 +msgid "GitHub and GitLab also both offer community features such as issues that allow:" +msgstr "" + +#: ../../tutorials/intro.md:197 +msgid "you to communicate with your maintainers and contributor community" +msgstr "" + +#: ../../tutorials/intro.md:198 +msgid "users to report bugs, ask questions and request new features" +msgstr "" + +#: ../../tutorials/intro.md:199 +msgid "you to publicly keep track of enhancements and features you want to work on for your package." +msgstr "" + +#: ../../tutorials/intro.md:201 +msgid "Continuous integration and continuous deployment" +msgstr "" + +#: ../../tutorials/intro.md:203 +msgid "GitHub and GitLab also provide continuous integration and continuous deployment (CI/CD). Continuous integration (CI) refers to a platform that automatically runs a specific job when a certain event occurs, whereas continuous deployment (CD) is an extension of CI that refers to not only running or building but also to publishing the final outputs somewhere." +msgstr "" + +#: ../../tutorials/intro.md:205 +msgid "**An example of Continuous integration:**" +msgstr "" + +#: ../../tutorials/intro.md:207 +msgid "When someone submits a change to your code, your tests will run across different operating systems and the code will be checked for format issues." +msgstr "" + +#: ../../tutorials/intro.md:209 +msgid "**An example of Continuous deployment:**" +msgstr "" + +#: ../../tutorials/intro.md:211 +msgid "When you are ready to release your package to PyPI, a continuous deployment operation might be triggered on release to publish your package to PyPI." +msgstr "" + +#: ../../tutorials/intro.md:213 +msgid "Integrated CI/CD will help you maintain your software, ensuring that changes to the code don't break things unexpectedly. They can also help you maintain code style and format consistency for every new change to your code." +msgstr "" + +#: ../../tutorials/intro.md:222 +msgid "The lifecycle of a scientific Python package." +msgstr "" + +#: ../../tutorials/intro.md:225 +msgid "When should you turn your code into a Python package?" +msgstr "" + +#: ../../tutorials/intro.md:227 +msgid "You may be wondering, what types of code should become a Python package that is both on GitHub and published to PyPI and/or conda-forge." +msgstr "" + +#: ../../tutorials/intro.md:229 +msgid "There are a few use cases to consider:" +msgstr "" + +#: ../../tutorials/intro.md:231 +msgid "**Creating a basic package for yourself:** Sometimes you want create a package for your own personal use. This might mean making your code locally pip installable and you may also want to publish it to GitHub. In that case you don't expect others to use your code, and as such you may only have documentation for you and your future self if you need to update the package." +msgstr "" + +#: ../../tutorials/intro.md:233 +msgid "An example of this type of package might be a set of functions that you write that are useful across several of your projects. It could be useful to have those functions available to all of your projects." +msgstr "" + +#: ../../tutorials/intro.md:236 +msgid "LINK to pip installable lesson when it's published - it's in review now" +msgstr "" + +#: ../../tutorials/intro.md:239 +msgid "**Creating a package for the community:** In other cases, you may create some code that you soon realize might also be useful to not just you, but to other people as well. In that case, you might consider both creating the package, publishing it on GitHub, and because other users may be using it, you may make use of GitHub's infrastructure including CI/CD pipelines and issue trackers. Because you want other people to use your package, you will want to also include LICENSE information, documentation for users and contributors and tests. This type of package is most often published to PyPI." +msgstr "" + +#: ../../tutorials/intro.md:242 +msgid "For example, all of the [pyOpenSci packages](https://www.pyopensci.org/python-packages.html) are public facing with an intended audience beyond just the maintainers." +msgstr "" + +#: ../../tutorials/intro.md:244 +msgid "Packages that you expect others to use should be well-scoped" +msgstr "" + +#: ../../tutorials/intro.md:246 +msgid "Ideally the code in your Python package is focused on a specific theme or use case. This theme is important as it's a way to scope the content of your package." +msgstr "" + +#: ../../tutorials/intro.md:248 +msgid "It can be tricky to decide when your code becomes something that might be more broadly useful to others. But one question you can ask yourself is - is your code written specifically for a single research project? Or could it have a broader application across multiple projects in your domain?" +msgstr "" + +#: ../../tutorials/intro.md:250 +msgid "How does this relate to code for a research project?" +msgstr "" + +#: ../../tutorials/intro.md:253 +msgid "A [Research Compendium](https://the-turing-way.netlify.app/reproducible-research/compendia.html) is an organized set of code, data and documentation that supports a specific research project. It aims to enhance the reproducibility and transparency of research by providing a comprehensive record of the methods, data, and analyses used in a study." +msgstr "" + +#: ../../tutorials/intro.md:258 +msgid "A Python package is a collection of modules that can be used to perform a specific set of tasks. These tasks should be applicable to numerous workflows. As such a Python package is more generalizable than a Research Compendium which supports a specific project." +msgstr "" + +#: ../../tutorials/intro.md:263 +msgid "[Read about `Good enough practices in scientific computing`](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1005510)" +msgstr "" + +#: ../../tutorials/intro.md:264 +msgid "[Learn more about research compendia (also called repo-packs) in this blog post.](https://lorenabarba.com/blog/how-repro-packs-can-save-your-future-self/)" +msgstr "" + +#: ../../tutorials/intro.md:267 +msgid "Below are a few examples well scoped pyOpenSci packages:" +msgstr "" + +#: ../../tutorials/intro.md:269 +msgid "[Crowsetta](https://crowsetta.readthedocs.io/en/latest/): is a package designed to work with annotating animal vocalizations and bioacoustics data. This package helps scientists process different types of bioacoustic data rather than focusing on a specific individual research application associated with a user-specific research workflow." +msgstr "" + +#: ../../tutorials/intro.md:270 +msgid "[Pandera](https://www.union.ai/pandera) is another more broadly used Python package. Pandera supports data testing and thus also has a broader research application." +msgstr "" + +#: ../../tutorials/intro.md:272 +msgid "Matplotlib as an example" +msgstr "" + +#: ../../tutorials/intro.md:274 +msgid "At the larger end of the user spectrum, Matplotlib is a great example. Matplotlib does one thing really well:" +msgstr "" + +#: ../../tutorials/intro.md:277 +msgid "_It creates visual plots of data._" +msgstr "" + +#: ../../tutorials/intro.md:279 +msgid "Thousands of people use Matplotlib for different plotting applications using different types of data. While few scientific packages will have the same broad application and large user base that Matplotlib has, the idea of scoping out what your package does is still important." +msgstr "" + +#: ../../tutorials/intro.md:285 +msgid "Code should also be clean & readable & documented" +msgstr "" + +#: ../../tutorials/intro.md:287 +msgid "The code in your package should also be clean, readable, and well documented." +msgstr "" + +#: ../../tutorials/intro.md:289 +msgid "**Clean code:** Clean code refers to code that uses expressive variable names, is concise and doesn't repeat itself. You can learn about best practices for clean code in future pyOpenSci tutorials." +msgstr "" + +#: ../../tutorials/intro.md:293 +msgid "**Readable code:** readable code is code written with a consistent style. You can use linters and code formatters such as black and flake8 to ensure this consistency throughout your entire package. [Learn more about code formatters here.](../package-structure-code/code-style-linting-format)" +msgstr "" + +#: ../../tutorials/intro.md:297 +msgid "**Documented code:** documented code is written using docstrings that help a user understand both what the functions and methods in your code do and also what the input and output elements of each function are. [You can learn more about docstrings in our guide, here.](../documentation/write-user-documentation/document-your-code-api-docstrings)" +msgstr "" + +#: ../../tutorials/intro.md:301 +msgid "Making your package installable - publishing to PyPI & conda-forge" +msgstr "" + +#: ../../tutorials/intro.md:303 +msgid "Python packages and environments" +msgstr "" + +#: ../../tutorials/intro.md:305 +msgid "You can install a Python package into a Python environment in the same way you might install NumPy or Pandas. Installing your package into an environment allows you to access it from any code run with that specific Python environment activated." +msgstr "" + +#: ../../tutorials/intro.md:311 +msgid "Diagram showing the steps associated with creating a package and then installing it. The first arrow says your package and the second says pip install package. The second arrow leads to a box that represents a Python environment that already has some packages installed such as Pandas and NumPy. Your package will also get installed into that same environment when you pip install it." +msgstr "" + +#: ../../tutorials/intro.md:313 +msgid "You don't have to publish to PyPI to make your code installable. With the correct file structure and project metadata you can make your code installable locally on your computer and use it for projects that you are working on without having to ever publish to PyPI. Publishing to PyPI is useful when you want to make your code public-facing and share it with others." +msgstr "" + +#: ../../tutorials/intro.md:320 +msgid "Publishing a package to PyPI / Conda-Forge" +msgstr "" + +#: ../../tutorials/intro.md:322 +msgid "If you want to make your package directly installable without having to download the code to your computer locally then you need to publish it in a repository such as **PyPI** or **conda-forge**." +msgstr "" + +#: ../../tutorials/intro.md:326 +msgid "Learn [how to publish your package to PyPI in this tutorial.](publish-pypi.md)" +msgstr "" + +#: ../../tutorials/intro.md:328 +msgid "Then you can create a conda-forge recipe using the [Grayskull](https://github.com/conda/grayskull) tool. You can then submit this recipe to conda-forge." +msgstr "" + +#: ../../tutorials/intro.md:330 +msgid "[You will learn more about the conda-forge publication process here.](publish-conda-forge.md)" +msgstr "" + +#: ../../tutorials/intro.md:333 +msgid "Graphic showing the high level packaging workflow. On the left you see a graphic with code, metadata and tests in it. Those items all go into your package. Documentation and data are below that box because they aren't normally published in your packaging wheel distribution. An arrow to the right takes you to a build distribution files box. That box leads you to either publishing to TestPyPI or the real PyPI. From PyPI you can then connect to conda-forge for an automated build that sends distributions from PyPI to conda-forge." +msgstr "" + +#: ../../tutorials/intro.md:335 +msgid "In the image above, you can see the steps associated with publishing your package on PyPI and conda-forge. Note that the distribution files that PyPI requires are the [sdist](#python-source-distribution) and [wheel](#python-wheel) files. Once you are ready to make your code publicly installable, you can publish it on PyPI. Once your code is on PyPI it is straight forward to then publish to conda-forge. You create a recipe using the Grayskull package and then you open a pr in the conda-forge recipe repository. You will learn more about this process in the [conda-forge lesson](/tutorials/publish-conda-forge)." +msgstr "" + +#: ../../tutorials/intro.md:339 +msgid "Yay, your package has users! Now what?" +msgstr "" + +#: ../../tutorials/intro.md:341 +msgid "As the community using your package grows, you may also find yourself managing users, contributors, and others who want to interact with your package. It’s important to consider all this before you dive into development. Once you have a user base in the community, people will depend upon your code to work and will need direction regarding how to use it." +msgstr "" + +#: ../../tutorials/intro.md:343 +msgid "To support your community, you'll want to add things like:" +msgstr "" + +#: ../../tutorials/intro.md:345 +msgid "[a development guide that documents your maintainer workflow process ](/documentation/repository-files/development-guide.md)" +msgstr "" + +#: ../../tutorials/intro.md:346 +msgid "[a code of conduct to defines community interaction standards and expectations](/documentation/repository-files/code-of-conduct-file.md)" +msgstr "" + +#: ../../tutorials/intro.md:347 +msgid "[a contributing guide that helps users understand expectations associated with making contributions to your project](/documentation/repository-files/contributing-file.md)" +msgstr "" + +#: ../../tutorials/intro.md:349 +msgid "Support for contributors and maintainers" +msgstr "" + +#: ../../tutorials/intro.md:351 +msgid "If you intend for others to use and contribute to your code, consider who will maintain it over time. You will want a **contributing and development** guide to help new potential contributors get started with contributing to your package, as well as a **code of conduct** to ensure community interactions remain healthy both for you and your contributors and maintainer team." +msgstr "" + +#: ../../tutorials/intro.md:353 +msgid "The elements above are also important for future maintenance of your package. In the case that you are no long able to maintain it or simply want extra help, development, and contributing documentation will help you onboard new maintainers." +msgstr "" + +#: ../../tutorials/intro.md:358 +msgid "What's next?" +msgstr "" + +#: ../../tutorials/intro.md:360 +msgid "In future lessons you will learn more about the infrastructure around a published Python package that makes it both easier to maintain, easier for others to contribute to and easier for other scientists to use. However, first we want to get you to your initial goal of publishing a Python package." +msgstr "" + +#: ../../tutorials/intro.md:362 +msgid "In this next lesson you will learn how to create a basic installable Python package. Make your code pip installable " +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:1 +msgid "Publish your Python package that is on PyPI to conda-forge" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:3 +msgid "In the previous lessons, you've learned:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:5 +msgid "How to [create the most basic version of a Python package](installable-code.md). This entailed making your code installable." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:6 +msgid "[How to publish your Python package to PyPI](publish-pypi)" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:7 +msgid "How to add a `README` and `LICENSE` file to your package" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:8 +msgid "How to setup your `pyproject.toml` file with all of the metadata that PyPI requires and also metadata that will be helpful for users to find your package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:10 +msgid "If you have gone through all of the above lessons, you are now ready to publish your package on conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:13 +msgid "**IMPORTANT:** Please do not practice publishing your package to conda-forge. You should only publish to conda-forge when you have a package on pypi.org that you plan to maintain." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:19 +#: ../../tutorials/publish-pypi.md:17 +msgid "In this lesson you will learn how to:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:21 +msgid "Create a conda-forge yaml recipe for your package using Grayskull" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:22 +msgid "Submit the recipe (yaml file) to the conda-forge staged recipes repository as a pull request" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:23 +msgid "Maintain your conda-forge package by creating new releases for your package on PyPI" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:26 +msgid "Once your package is on PyPI you can then easily publish it to conda-forge using the [grayskull](https://conda.github.io/grayskull/) tool. You do not need to build the package specifically for conda, conda-forge will build from your PyPI source distribution file (sdist)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:33 +msgid "Image showing the progression of creating a Python package, building it and then publishing to PyPI and conda-forge. You take your code and turn it into distribution files (sdist and wheel) that PyPI accepts. Then there is an arrow towards the PyPI repository where ou publish both distributions. From PyPI if you create a conda-forge recipe you can then publish to conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:35 +msgid "Once you have published both package distributions (the source distribution and the wheel) to PyPI, you can then publish to conda-forge. Conda-forge requires a source distribution on PyPI in order to build your package on conda-forge. You do not need to rebuild your package to publish to conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:38 +msgid "What is conda-forge?" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:40 +msgid "conda is an open source package and environment management tool that can be used to install tools from the different channels on Anaconda.org." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:43 +msgid "You can think about a channel as a specific location where a group of packages are stored and can be installed from using a command such as `conda install packagename`. In the case of conda channels, some of these channels such as the `defaults` channel, is managed by Anaconda (the company). Only Anaconda can decide what packages are available in the `defaults` channel. However, the conda-forge (and bioconda) channel are community-managed channels. Anyone can submit a package to these channels however they must pass a technical review in the [staged-recipes GitHub repository](https://github.com/conda-forge/staged-recipes) to be published." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:46 +msgid "[Learn more about conda channels here.](#about-conda)" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:50 +msgid "Graphic with the title Python package repositories. Below it says anything hosted on PyPI can be installed using pip install. Packaging hosted on a conda channel can be installed using conda install. Below that there are two rows. The top row says conda channels. Next to it are three boxes one with conda-forge, community maintained; bioconda and then default - managed by the Anaconda team. Below that there is a row that says PyPI servers. PyPI - anyone can publish to PyPI and test PyPI (a testbed server for you to practice)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:52 +msgid "Conda channels represent various repositories that you can install packages from. Because conda-forge is community maintained, anyone can submit a recipe there. PyPI is also a community maintained repository. Anyone can submit a package to PyPI and test PyPI. Unlike conda-forge there are no manual checks of packages submitted to PyPI." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:55 +msgid "Why publish to conda-forge" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:57 +msgid "There are many users, especially in the scientific Python ecosystem that use conda as their primary package manager / environment tool. Thus, having packages available to these users on the conda-forge channel is useful. In some cases packages on conda-forge can minimize dependency conflicts that can occur when mixing installations using pip and conda. This is particularly important for the spatial ecosystem." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:59 +msgid "How publishing to conda-forge works" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:61 +msgid "Once you have built and published your package to PyPI, you have everything that you need to publish to conda-forge. There is no additional build step needed to publish to conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:63 +msgid "Conda-forge will build your package from the source distribution which you [published to PyPI in the previous lesson](publish-pypi) using the recipe that you will create below." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:65 +msgid "Conda-forge publication steps" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:68 +msgid "Image showing the steps associated with publishing to conda-forge. Check out the caption below for a detailed description." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:70 +msgid "The steps for publishing to conda-forge begin with publishing your Python package to PyPI. Once you have published to PyPI you can then create a yaml file recipe that can be submitted to the conda-forge staged recipes repository for review. Once that recipe is accepted, your package will get it's on repository (known as a feedstock) on conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:73 +msgid "The steps to publish to conda-forge are:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:75 +msgid "Publish your Python package distribution files (sdist & wheel) to PyPI" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:76 +msgid "Create a conda-forge recipe, which is a yaml file with instructions on how to build your package on conda-forge, using the grayskull[^grayskull] package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:77 +msgid "Submit the recipe (yaml file) to the conda-forge staged recipes repository as a pull request for review. [Click here for an example submission from pyOpenSci.](https://github.com/conda-forge/staged-recipes/pull/25173)" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:79 +msgid "Once someone from the conda-forge team reviews your pull request, you may need to make some changes. Eventually the pull request will be approved and merged." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:81 +msgid "Once your recipe is accepted and merged on conda-forge, users can install your package using:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:83 +msgid "`conda install -c conda-forge your-package`" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:85 +msgid "You only create the recipe once. Once the recipe is accepted and merged, you only need to maintain the repository." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:87 +msgid "Maintaining a conda-forge package" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:89 +msgid "Once your package is on conda-forge, the repository will track release activity on the package's PyPI repository. Any time you make a new PyPI release with a new source distribution, conda-forge will build and update your conda-forge repository (also known as a feedstock)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:91 +msgid "When the update is processed, the friendly conda-forge bot will create a new pull request with an updated distribution recipe in your feedstock." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:93 +msgid "You can review that pull request and then merge it once all of the continuous integration tests pass." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:95 +msgid " How to Publish your package on conda-forge" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:97 +msgid "It's time to add your package to the conda-forge channel. Remember that your package needs to be on PyPI before the steps below will work. And also remember that the team managing conda-forge are all volunteers." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:100 +msgid "Be sure that your package is on PyPI.org (not test.pypi.org) before you attempt to publish to conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:103 +msgid "Only submit your package to conda-forge if you intend to maintain it over time." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:106 +msgid "Note - this is a tutorial aimed to help you get your package onto conda-forge. The official conda documentation for this processed [is here](https://conda-forge.org/docs/maintainer/adding_pkgs.html)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:108 +msgid "Step 1: Install grayskull" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:110 +msgid "First, [install grayskull](https://conda.github.io/grayskull/user_guide.html). You can install it using either pip:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:116 +msgid "or conda" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:122 +msgid "To run this command, use the same shell / terminal that you have been using to run hatch commands in the previous tutorials." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:127 +msgid "You can also install grayskull using pipx[^pipx]. pipx is a tool that allows you to install commonly used tools that you might want to have available across multiple Python environments rather than installing the package into every Python environment that you create." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:130 +msgid "Step 2: Fork and clone the conda-forge staged-recipes repository" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:132 +msgid "Next, open your shell and `cd` to a location where you want to clone the **conda-forge/staged-recipes** repository." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:133 +msgid "fork and clone the [conda-forge/staged-recipes GitHub repository](https://github.com/conda-forge/staged-recipes)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:134 +msgid "Create a new branch in your fork rather than submitting from the main branch of your fork. We suggest naming the branch your package's name." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:136 +msgid "`git checkout -b your-package-name `" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:138 +msgid "In bash, `cd` into the `staged-recipes/recipes` folder" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:146 +msgid "Next, create a new branch in your `conda-forge/staged-recipes` cloned repository. You might want to make that branch the same name as your package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:157 +msgid "Step 3: Create your conda-forge recipe" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:159 +msgid "Next, navigate to the recipes directory" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:161 +msgid "If you run `ls` here, you will notice there is an example directory with an example recipe for you to look at." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:173 +msgid "Next, run `grayskull pypi your-package-name` to generate a recipe." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:217 +msgid "Grayskull will pull metadata about your package from PyPI. It does not use your local installation of the package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:218 +msgid "An internet connection is needed to run the `grayskull pypi your-package-name` step." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:221 +msgid "When you run grayskull, it will grab the latest distribution of your package from PyPI and will use that to create a new recipe." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:223 +msgid "The recipe will be saved in a directory named after your package's name, wherever you run the command." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:225 +msgid "`recipes/packagename/meta.yaml`" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:227 +msgid "At the very bottom of the grayskull output, it will also tell you where it saved the recipe file." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:230 +msgid "Open the meta.yaml file. The finished `meta.yaml` file that grayskull creates should look like the example below:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:277 +msgid "Step 3b: Bug fix - add a home url to the about: section" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:279 +msgid "There is currently a small bug in Grayskull where it doesn't populate the home: element of the recipe. If you don't include this, [you will receive an error message](https://github.com/conda-forge/staged-recipes/pull/25173#issuecomment-1917916528) from the friendly conda-forge linter bot." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:293 +msgid "to fix this, open your meta.yaml file in your favorite text editor." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:294 +msgid "and add a home: element to the about section" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:296 +msgid "The about section will look like this after you create your recipe." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:306 +msgid "Below you add a home: element. If you have a project home page / website you can use that url. Otherwise, you can also use your PyPI landing page." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:317 +msgid "Step 4: tests for conda-forge" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:319 +msgid "Next, have a look at the tests section in your **meta.yaml** file. At a minimum you should import your package or the main modules associated with your package and run `pip check`." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:321 +msgid "`pip check` will ensure that your package installs properly with all of the proper dependencies." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:333 +msgid "If you have more advanced tests that you wish to run, you can add them here. However, you can also simply leave the tests section as it is." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:335 +msgid "Step 4: Submit a pull request to the staged-recipes repository" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:337 +msgid "Once you have completed all of the above, you are ready to open up a pull request in the `conda-forge/staged-recipes repository`." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:339 +msgid "Submit a pull request from your fork/branch of the staged-recipes repository." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:340 +msgid "Remember that the conda-forge maintainers are volunteers. Be patient for someone to respond and supportive in your communication with them." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:0 +msgid "Conda-forge checklist help" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:346 +msgid "Conda-forge Staged-recipes Pull Request Checklist" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:348 +msgid "When you submit your package to conda-forge, the pull request template includes a list of checks that you want to ensure you have covered." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:350 +msgid "Below we break down each element of that list." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:352 +msgid "Pull request template checklist tips" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:355 +msgid "-[x] Title of this PR is meaningful: e.g. \"Adding my_nifty_package\", not \"updated meta.yaml\"." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:357 +msgid "**Translation:** Make sure that your pull request title is specific. We suggest something like: `Add recipe for `" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:360 +msgid "-[x] License file is packaged (see [here](https://github.com/conda-forge/staged-recipes/blob/5eddbd7fc9d1502169089da06c3688d9759be978/recipes/example/meta.yaml#L64-L73) for an example)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:362 +msgid "**Translation:** You should have a LICENSE file included in your package's source distribution. If you have followed the pyOpenSci tutorials then you already have a LICENSE file and are likely using the MIT license. When you run `hatch build`, it will bundle that file into the output [source distribution file (which is the tar.gz file)](python-source-distribution) that conda-forge will use to build your package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:364 +msgid "[x] Source is from official source." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:366 +msgid "**Translation:** If your package is on PyPI as you learned in the [previous lesson on publishing your Python package](publish-pypi) then you are in good shape. conda-forge prefers that your distribution is published to a known repository." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:368 +msgid "-[x] Package does not vendor other packages. (If a package uses the source of another package, they should be separate packages or the licenses of all packages need to be packaged)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:370 +msgid "**Translation:** If the code base in your package is your own and it all shares the same LICENSE then you are in good shape. If you have code taken from other packages then you may need to declare that and include licenses for that code if it is different. If you followed these tutorials then you do not have any vendored code." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:372 +msgid "-[x] If static libraries are linked in, the license of the static library is packaged." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:374 +msgid "-[x] Package does not ship static libraries. If static libraries are needed, [follow CFEP-18](https://github.com/conda-forge/cfep/blob/main/cfep-18.md)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:376 +msgid "**Translation:** A static library refers to a copy of a package built into your package. If your package is a pure Python package, then you can check that your package does not ship static libraries as this does not apply to you." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:378 +msgid "The pyOpenSci tutorials are all pure Python and as such do not use static libraries in a linked or shipped (included in the package distribution) format." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:380 +msgid "If your package has a more complex build that includes links to extensions written in other languages such as C++, then be sure to include the proper licenses for those extensions in your metadata." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:385 +msgid "If you want to learn more about static libraries, then [this overview](https://pypackaging-native.github.io/background/compilation_concepts/#shared-vs-static-libraries) might help." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:388 +msgid "-[ ] Build number is 0." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:390 +msgid "**Translation:** The build number in your recipe is right below the source location of your package's source distribution. `number: 0` is what you should see in that section of your recipe." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:403 +msgid "[x] A tarball (`url`) rather than a repo (e.g. `git_url`) is used in your recipe (see [here](https://conda-forge.org/docs/maintainer/adding_pkgs.html) for more details)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:405 +msgid "**Translation:** Here conda wants you to provide a link to the source distribution on PyPI rather than a link to your GitHub repository distribution. Notice above in the Source section of your recipe there is a `url:` section that provides a PyPI url that ends in tar.gz. That is a link to your source distribution that conda-forge will use." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:411 +msgid "[x] GitHub users listed in the maintainer section have posted a comment confirming they are willing to be listed there." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:413 +msgid "**Translation** Once you have submitted your recipe, be sure that all maintainers listed in your recipe respond acknowledging that they are ok with being listed as a maintainer for the conda-forge version of your package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:415 +msgid "[x] When in trouble, please check our [knowledge base documentation](https://conda-forge.org/docs/maintainer/knowledge_base.html) before pinging a team." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:417 +msgid "**Translation** The conda team are volunteers who spend their time supporting our community. Please try to troubleshoot on your own first before tagging one of them for help." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:419 +msgid "This is also why we don't suggest you publish to conda-forge as a practice run." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:423 +msgid "Once you create your pull request, a suite of CI actions will run that build and test the build of your package. A conda-forge maintainer will work with you to get your recipe in good shape and merged." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:427 +msgid "Image showing the 5 CI tasks that will run against your package in the GitHub interface after you'ce created a pull request." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:429 +msgid "Wait until all of the CI steps in your pull request have run. At that point your pull request is ready for review by a conda-forge maintainer." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:432 +msgid "In some cases getting all of the checks to run successfully in CI might take a bit of work. If you are struggling to get your recipe to build properly, you can ping the conda-forge maintainer team for help." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:434 +msgid "Please be patient and wait for them to respond." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:436 +msgid "conda-forge staged recipes and CI failures" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:439 +msgid "If your package is a pure Python package that can be installed on any type of computer (Windows, mac, linux) and has no architecture requirements (known as noarch: Python or no architecture requirements) then the conda-forge team only requires tests for Linux CI to pass." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:441 +msgid "So if tests for Windows and MAC OS fail, that is to be expected. In this case, don't worry about failing tests, the maintainer team can help you get your package published." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:444 +msgid "Once you have submitted your recipe, you can wait for the CI build to pass. If it's not passing, and you aren't sure why, a conda-forge maintainer can likely help you figure things out." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:446 +msgid "Once your recipe is built and merged, the conda team will create a new package repository for you similar to [this one for the GemGIS package](https://github.com/conda-forge/gemgis-feedstock)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:448 +msgid " Congratulations - you have added your package to conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:450 +msgid "The last part of this process is maintaining the repository. We cover that next." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:453 +msgid "Maintaining your conda-forge feedstock" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:455 +msgid "Every time you create a new release on PyPI, the conda-forge bots will recognize the release and will rebuild the newly released version of your package. This process may take a day or two to complete so be patient." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:457 +msgid "Once the conda-forge build is complete, all of the maintainers of your conda-forge feedstock will get a ping on GitHub that a new pull request has been opened." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:459 +msgid "Review the pull request. If all tests are passing, you can merge it. Shortly after merging your pull request, the conda-forge release will be available for users to install:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:461 +msgid "`conda install -c conda-forge yourpackage`" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:465 +msgid "If you have walked through this entire tutorial series you will now:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:467 +msgid "Understand [what a Python package is ](intro.md)" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:468 +msgid "Know how to [make your code installable](installable-code.md) into Python environments" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:469 +msgid "Know how to create a `pyproject.toml` file, a `README` file, and a `LICENSE` and code of conduct." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:470 +msgid "Know how to [publish your package to PyPI](publish-pypi.md) and" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:471 +msgid "Know how to publish your package to conda-forge" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:473 +msgid "The above are the basic steps that you need to take to create and publish a Python package. In a future tutorial series we will cover that basics of maintaining your package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:477 +msgid "[Grayskull blogpost](https://conda-forge.org/blog/2020/03/05/grayskull/)" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:478 +msgid "[Pipx documentation](https://pipx.pypa.io/stable/)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:1 +msgid "Publish your Python package to PyPI" +msgstr "" + +#: ../../tutorials/publish-pypi.md:4 +msgid "Make sure they add /dist to their .gitignore file. We have not discussed GitHub workflows anywhere yet. Where does that fit?" +msgstr "" + +#: ../../tutorials/publish-pypi.md:8 +msgid "In the previous Python packaging lessons, you've learned:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:10 +msgid "What a Python package is" +msgstr "" + +#: ../../tutorials/publish-pypi.md:11 +msgid "How to make your code installable." +msgstr "" + +#: ../../tutorials/publish-pypi.md:19 +msgid "Build your package's source (sdist) and wheel distributions" +msgstr "" + +#: ../../tutorials/publish-pypi.md:20 +msgid "Setup an account on TestPyPI (the process is similar for PyPI)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:21 +msgid "Publish your package to TestPyPI and PyPI" +msgstr "" + +#: ../../tutorials/publish-pypi.md:23 +msgid "You will do all of your development work in this lesson using [Hatch](https://hatch.pypa.io/latest/)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:25 +msgid "Once your package is on PyPI you can publish it to conda-forge (which is a channel on conda) using [Grayskull](https://conda.github.io/grayskull/)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:28 +msgid "You will learn how to publish to conda-forge in the [next lesson](publish-conda-forge)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:32 +msgid "Graphic showing the high level packaging workflow. On the left you see a graphic with code, metadata and tests in it. Those items all go into your package. An arrow to the right takes you to a build distribution files box. Another arrow to the right takes you to a publish to PyPI box which has an arrow containing sdist and wheel that notes those files go to PyPI for hosting. From PyPI is an arrow containing sdist since you can then connect to conda-forge for an automated build that sends distributions from PyPI to conda-forge." +msgstr "" + +#: ../../tutorials/publish-pypi.md:34 +msgid "You need to build your Python package in order to publish it to PyPI (or Conda). The build process organizes your code and metadata into a distribution format that can be uploaded to PyPI and subsequently downloaded and installed by users." +msgstr "" + +#: ../../tutorials/publish-pypi.md:37 +msgid "TestPyPI vs PyPI" +msgstr "" + +#: ../../tutorials/publish-pypi.md:39 +msgid "There are two repositories associated with PyPI to which you can upload your Python package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:42 +msgid "**[TestPyPI](https://test.pypi.org):** TestPyPI is a package repository provided by PyPI that you can use for testing that your package can be uploaded, downloaded, and installed correctly. This is a great place to practice and learn how to publish a package without exposing your incomplete package on the real PyPI service." +msgstr "" + +#: ../../tutorials/publish-pypi.md:43 +msgid "**[PyPI](https://pypi.org):** This is the live, production PyPI repository where you can officially publish your Python package, and from which users will get your package. IMPORTANT: Only publish your package to PyPI when you are ready for it to be used by others and/or confident that it will become a package that you will maintain. PyPI is not a place to practice learning how to publish a Python package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:45 +msgid "The steps for publishing on TestPyPI vs. PyPI are similar with the exception of a different url. We will point out where they differ." +msgstr "" + +#: ../../tutorials/publish-pypi.md:48 +msgid "4 Steps for publishing a Python package on TestPyPI (or PyPI)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:50 +msgid "In this lesson you will learn how to publish your package to TestPyPI using [Hatch](https://hatch.pypa.io/latest/). There are 4 things that you need to do to publish your Python package: to TestPyPI. You need to:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:55 +msgid "**Create a package development environment**" +msgstr "" + +#: ../../tutorials/publish-pypi.md:56 +msgid "[**Build your package using `hatch build`**](../package-structure-code/python-package-distribution-files-sdist-wheel). Building a package is the process of turning your code into two types of distribution files: sdist and wheel. The wheel distribution file is particularly important for users who will `pip install` your package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:57 +msgid "**Create an account on TestPyPI (or PyPI)**: You will need to create a TestPyPI account and associated token which provides permissions for you to upload your package. When you later publish your package to PyPI, you will need a separate PyPI account and token." +msgstr "" + +#: ../../tutorials/publish-pypi.md:58 +msgid "**Publish to TestPyPI using `hatch publish`**" +msgstr "" + +#: ../../tutorials/publish-pypi.md:60 +msgid "In a future lesson, you will learn how to create an automated GitHub Actions workflow that publishes an updated version of your package to PyPI every time you create a GitHub release." +msgstr "" + +#: ../../tutorials/publish-pypi.md:64 +msgid "Learn more about building Python packages in our guide" +msgstr "" + +#: ../../tutorials/publish-pypi.md:68 +msgid "[Learn more about what building a Python package is](../package-structure-code/python-package-distribution-files-sdist-wheel)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:69 +msgid "[Learn more about the package distribution file that PyPI needs called the wheel](#python-wheel)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:70 +msgid "[Learn more about the package distribution file that conda-forge will need on PyPI called the sdist (source distribution)](#python-source-distribution)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:73 +msgid "Step 1: Create a Python package development environment" +msgstr "" + +#: ../../tutorials/publish-pypi.md:75 +msgid "The first step in building your package is to create a development environment. The Python environment will contain all of the dependencies needed to both install and work on your package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:77 +msgid "Use Hatch to create your environment." +msgstr "" + +#: ../../tutorials/publish-pypi.md:85 +msgid "Then view all of the current environments that hatch has access to:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:97 +msgid "Then activate the environment. Note that when you call a shell from a Hatch environment, it will automatically install your package into the environment in development or editable mode." +msgstr "" + +#: ../../tutorials/publish-pypi.md:107 +msgid "View what's in the environment using `pip list`:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:123 +msgid "At any time you can exit the environment using `exit`." +msgstr "" + +#: ../../tutorials/publish-pypi.md:137 +msgid "Hatch and environments" +msgstr "" + +#: ../../tutorials/publish-pypi.md:139 +msgid "Behind the scenes when hatch creates a new virtual environment, by default it uses venv[^venv] which is the default environment management tool that comes with Python installations." +msgstr "" + +#: ../../tutorials/publish-pypi.md:142 +msgid "Hatch will:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:144 +msgid "Create a new virtualenv (venv) that is located on your computer." +msgstr "" + +#: ../../tutorials/publish-pypi.md:145 +msgid "Install your package into the environment in editable mode (similar to `python -m pip install -e`). This means it installs both your project and your project's dependencies as declared in your pyproject.toml file." +msgstr "" + +#: ../../tutorials/publish-pypi.md:147 +msgid "Step 2: Build your package's sdist and wheel distributions" +msgstr "" + +#: ../../tutorials/publish-pypi.md:149 +msgid "Once you have your development environment setup, you are ready to build your package using Hatch. Remember that building is the process of turning your Python package file structure into two distribution files:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:151 +msgid "The [wheel distribution](#python-wheel) is a pre-built version of your package. It useful for users as it can be directly installed using a tool such as `pip`. This file has the extension `.whl`." +msgstr "" + +#: ../../tutorials/publish-pypi.md:152 +msgid "The [source distribution](#python-source-distribution) contains the files that make up your package in an unbuilt format. This file will have the extension `.tar.gz`." +msgstr "" + +#: ../../tutorials/publish-pypi.md:154 +msgid "You will use Hatch as a **Front end** tool that builds your package's sdist and wheel using the [hatchling](https://hatch.pypa.io/latest/) build back-end. The hatchling build back-end is used because you declared it in your pyproject.toml file in the [previous lesson](installable-code)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:158 +msgid "To build your package run `hatch build`:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:169 +msgid "Learn more about building a Python package" +msgstr "" + +#: ../../tutorials/publish-pypi.md:171 +msgid "You can learn more about building in the [build page of our packaging guide](../package-structure-code/python-package-distribution-files-sdist-wheel)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:175 +msgid "The sdist is important if you wish to [publish your package to conda-forge](publish-conda-forge). You will learn about this in a later lesson." +msgstr "" + +#: ../../tutorials/publish-pypi.md:179 +msgid "➜ hatch build ────────────────────────────────────── sdist ────────────────────────────────────── dist/pyospackage-0.1.tar.gz ────────────────────────────────────── wheel ────────────────────────────────────── dist/pyospackage-0.1-py3-none-any.whl" +msgstr "" + +#: ../../tutorials/publish-pypi.md:186 +msgid " Congratulations - you've created your Python package distribution files " +msgstr "" + +#: ../../tutorials/publish-pypi.md:188 +msgid "You've now built your Python package and created your package distribution files. The next step is to setup your account on TestPyPI so you can publish your package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:191 +msgid "Step 3. Setup your TestPyPI account" +msgstr "" + +#: ../../tutorials/publish-pypi.md:193 +msgid "Next, you'll setup an account on TestPyPI. Remember that you are using TestPyPI here instead of the real PyPI as a way to safely learn how to publish a package without accidentally \"releasing\" your package before it's ready." +msgstr "" + +#: ../../tutorials/publish-pypi.md:197 +msgid "TestPyPI vs. PyPI" +msgstr "" + +#: ../../tutorials/publish-pypi.md:198 +msgid "If you have a package that you are confident belongs on PyPI, all of the steps below will also work for you. When you publish using Hatch, you will call `hatch publish` to publish directly to PyPI instead of `hatch publish -r test` which publishes to TestPyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:201 +msgid "[Open up a web browser and go to the TestPyPI website](https://test.pypi.org/)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:202 +msgid "[Create an account](https://test.pypi.org/account/register/) if you don't already have one. Be sure to store your password in a safe place!" +msgstr "" + +#: ../../tutorials/publish-pypi.md:203 +msgid "Once you have an account setup, login to it." +msgstr "" + +#: ../../tutorials/publish-pypi.md:204 +msgid "Search on [https://test.pypi.org/](https://test.pypi.org/) (and also on [https://pypi.org/](https://pypi.org/)) to ensure that the package name that you have selected doesn't already exist. If you are using our test pyosPackage, then we suggest that you add your name or GitHub username to the end of the package name to ensure it's unique." +msgstr "" + +#: ../../tutorials/publish-pypi.md:206 +msgid "Example: `pyosPackage_yourNameHere`." +msgstr "" + +#: ../../tutorials/publish-pypi.md:0 +msgid "Renaming your project before publishing" +msgstr "" + +#: ../../tutorials/publish-pypi.md:211 +msgid "Required" +msgstr "" + +#: ../../tutorials/publish-pypi.md:213 +msgid "Search your publishing location(s) to make sure your new name isn't taken ([TestPyPI](https://test.pypi.org/), [PyPI](https://pypi.org/), [conda-forge](https://conda-forge.org/packages/))" +msgstr "" + +#: ../../tutorials/publish-pypi.md:214 +msgid "Update the project name in your pyproject.toml file (e.g. `name = \"pyospackage_yourNameHere\"`)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:215 +msgid "Update the module folder name to be the same (e.g. `src/pyospackage_yourNameHere`)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:216 +msgid "Rebuild your project (`hatch build`)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:217 +msgid "Publish your package to capture the name (continue this tutorial!)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:219 +msgid "Recommended" +msgstr "" + +#: ../../tutorials/publish-pypi.md:221 +msgid "Update the GitHub repository name to align with the new package name" +msgstr "" + +#: ../../tutorials/publish-pypi.md:222 +msgid "Update your local project folder to match the new package name (e.g. `pyospackage_yourNameHere/src`)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:223 +msgid "Update mentions of your repository name in other files (e.g. `README.md`)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:227 +msgid "This is a screenshot of the TestPyPI website. At the top in the search bar, you can see the search for pyosPackage. The search return says there were no results for pyosPackage Did you mean probpackage" +msgstr "" + +#: ../../tutorials/publish-pypi.md:229 +msgid "Before you try to upload to TestPyPI, check to see if the name of your package is already taken. You can do that using the search box at the top of the TestPyPI website." +msgstr "" + +#: ../../tutorials/publish-pypi.md:233 +msgid "Setup 2-factor (2FA) authentication" +msgstr "" + +#: ../../tutorials/publish-pypi.md:235 +msgid "2-factor authentication is a secure login process that allows you to use a backup device that only you can access to validate that the person logging in is really you. It addresses the issue of password phishing where someone else gains access to a password and can login to your account." +msgstr "" + +#: ../../tutorials/publish-pypi.md:238 +msgid "This matters on PyPI because someone could login to your account and upload a version of your package that has security issues. These issues will then impact all of your users when they download and install that version of the package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:240 +msgid "2-factor authentication is required for PyPI authentication as of 1 January 2024." +msgstr "" + +#: ../../tutorials/publish-pypi.md:244 +msgid "Step 4. Create a package upload token" +msgstr "" + +#: ../../tutorials/publish-pypi.md:246 +msgid "To upload your package to TestPyPI (or PyPI), you will need to create a token for your account first, and should then create a package-specific token. (If you completed this step previously, you can reuse the tokens when you upload your package again.)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:248 +msgid "Why create package-specific tokens?" +msgstr "" + +#: ../../tutorials/publish-pypi.md:250 +msgid "It's ideal to create a package-specific token. When you create an account-wide token this allows anyone with access to the account to then access all of your TestPyPI (or PyPI) projects. By creating a package-specific token, you are limiting the scope of the token to only your specific package. This is just a safe way to set things up for you particularly if you are collaborating with others on package development." +msgstr "" + +#: ../../tutorials/publish-pypi.md:253 +msgid "Follow the steps below to create your token." +msgstr "" + +#: ../../tutorials/publish-pypi.md:255 +msgid "Login to TestPyPI and go to your account settings" +msgstr "" + +#: ../../tutorials/publish-pypi.md:256 +msgid "Scroll down to the **API tokens** section" +msgstr "" + +#: ../../tutorials/publish-pypi.md:257 +msgid "Click on the **Add API Token** button" +msgstr "" + +#: ../../tutorials/publish-pypi.md:258 +msgid "If you are new to using TestPyPI and don't have any packages there yet, OR if you have other packages on TestPyPI but are uploading a new package, you will need to create an account-wide token." +msgstr "" + +#: ../../tutorials/publish-pypi.md:259 +msgid "When you create your token, be sure to copy the token value and store it in a secure place before closing that browser." +msgstr "" + +#: ../../tutorials/publish-pypi.md:261 +msgid "Your token should look something like this:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:263 +msgid "`pypi-abunchofrandomcharactershere...`" +msgstr "" + +#: ../../tutorials/publish-pypi.md:265 +msgid "It should start with `pypi` followed by a dash and a bunch of characters." +msgstr "" + +#: ../../tutorials/publish-pypi.md:267 +msgid "Upload to TestPyPI using Hatch" +msgstr "" + +#: ../../tutorials/publish-pypi.md:269 +msgid "Once you have your token, you are ready to publish to TestPyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:272 +msgid "Run `hatch publish -r test`" +msgstr "" + +#: ../../tutorials/publish-pypi.md:274 +msgid "`-r` stands for repository. In this case because you are publishing to TestPyPI you will use `-r test`. Hatch will then ask for a username and credentials." +msgstr "" + +#: ../../tutorials/publish-pypi.md:276 +msgid "Add the word `__token__` for your username. This tells TestPyPI that you are using a token value rather than a username." +msgstr "" + +#: ../../tutorials/publish-pypi.md:277 +msgid "Paste your TestPyPI token value in at the `Enter your credentials` prompt:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:288 +msgid "If your credentials are valid, and you have already run `hatch build` and thus have your 2 distribution files in a `dist/` directory then Hatch will publish your package to TestPyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:292 +msgid "Hatch also has a caching system so once you enter your credentials it will remember them." +msgstr "" + +#: ../../tutorials/publish-pypi.md:295 +msgid "Install your package from TestPyPI" +msgstr "" + +#: ../../tutorials/publish-pypi.md:297 +msgid "Once your package upload is complete, you can install it from TestPyPI. You can find the installation instructions on the TestPyPI landing page for your newly uploaded package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:302 +msgid "A screenshot of the TestPyPI page for pyosPackage. It says pyosPackage 0.1.0 at the top with the pip install instructions below. The landing page of the package has information from the package's README file." +msgstr "" + +#: ../../tutorials/publish-pypi.md:304 +msgid "This is an example landing page for the pyosPackage that was just uploaded. Notice at the top of the page there are instructions for how to install the package from TestPyPI. You can simply copy that code and use it to install your package from TestPyPI locally." +msgstr "" + +#: ../../tutorials/publish-pypi.md:307 +msgid "As an example, [check out our pyOpenSci pyosPackage landing page on TestPyPI](https://test.pypi.org/project/pyosPackage/). Notice that the page has information about the current package version and also installation instructions as follows:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:311 +msgid "`python -m pip install -i https://test.pypi.org/simple/ pyosPackage`" +msgstr "" + +#: ../../tutorials/publish-pypi.md:314 +msgid "Publishing to TestPyPI vs PyPI While you can install from TestPyPI it's not recommended that you publish to TestPyPI as a permanent way to install your package. In fact, you cannot, because TestPyPI may delete accounts after a time. TestPyPI is a perfect place to learn how to publish your package and test the installation process. But your end goal should be to publish to PyPI once you have figured out your workflow and your package is ready to deploy." +msgstr "" + +#: ../../tutorials/publish-pypi.md:318 +msgid "Time to install your package" +msgstr "" + +#: ../../tutorials/publish-pypi.md:320 +msgid "On your computer, activate the development environment that you wish to install your newly published package in." +msgstr "" + +#: ../../tutorials/publish-pypi.md:322 +msgid "Run the installation instructions for your package from TestPyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:0 +msgid "Conda" +msgstr "" + +#: ../../tutorials/publish-pypi.md:0 +msgid "venv Mac / Linux" +msgstr "" + +#: ../../tutorials/publish-pypi.md:346 +msgid "The value of end-to-end tools like hatch, flit and poetry" +msgstr "" + +#: ../../tutorials/publish-pypi.md:347 +msgid "In this lesson you are using Hatch and hatchling to create, build and publish your Python package. [Click here to learn about other packaging tools in the ecosystem.](../package-structure-code/python-package-build-tools.md)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:351 +msgid "teach them to setup trusted publisher for actions... in the actions lesson https://pypi.org/help/#twofa" +msgstr "" + +#: ../../tutorials/publish-pypi.md:354 +msgid "from PyPI: https://pypi.org/help/#apitoken - You can create a token for an entire PyPI account, in which case, the token will work for all projects associated with that account. Alternatively, you can limit a token's scope to a specific project." +msgstr "" + +#: ../../tutorials/publish-pypi.md:357 +msgid "Package-specific token vs trusted publisher" +msgstr "" + +#: ../../tutorials/publish-pypi.md:359 +msgid "For long run maintenance of your package, you have two options related to PyPI publication." +msgstr "" + +#: ../../tutorials/publish-pypi.md:362 +msgid "You can create a package-specific token which you will use to publish your package (manually) to PyPI. This is a great option if you don't wish to automate your PyPI publication workflow." +msgstr "" + +#: ../../tutorials/publish-pypi.md:363 +msgid "You can also create an automated publication workflow on GitHub using GitHub Actions. This is a great way to make the publication process easier and it also supports a growing maintainer team. In this case we suggest you don't worry about the token and instead setup a specific GitHub Actions that publishes your package when you make a release. You can then create a \"trusted publisher\" workflow on PyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:365 +msgid "You will learn how to create the automated trusted publisher workflow in a followup lesson." +msgstr "" + +#: ../../tutorials/publish-pypi.md:368 +msgid "OPTIONAL: If you want to use a manual token-based publication workflow" +msgstr "" + +#: ../../tutorials/publish-pypi.md:370 +msgid "If you plan to use your token regularly to publish to PyPI, we strongly recommend going through the above steps again to create a token specific to your new package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:373 +msgid "To do this:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:374 +msgid "Go to TestPyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:375 +msgid "Navigate to the \"Your Projects\" section of your account" +msgstr "" + +#: ../../tutorials/publish-pypi.md:376 +msgid "Click on the manage button for the project that you wish to add a token for" +msgstr "" + +#: ../../tutorials/publish-pypi.md:377 +msgid "Go to settings" +msgstr "" + +#: ../../tutorials/publish-pypi.md:378 +msgid "Click on \"Create a token for your-package-name-here\"" +msgstr "" + +#: ../../tutorials/publish-pypi.md:379 +msgid "Create the token and follow the steps above publish your package using the repository specific token." +msgstr "" + +#: ../../tutorials/publish-pypi.md:381 +msgid "And you're all done!" +msgstr "" + +#: ../../tutorials/publish-pypi.md:383 +msgid "You have published your package to TestPyPI!" +msgstr "" + +#: ../../tutorials/publish-pypi.md:385 +msgid "Congratulations. You have now successfully published your package to TestPyPI. If you have a package that is ready for real-world use on the real PyPI, then you can follow the same steps (with the differences noted above) to publish it on PyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:387 +msgid "Once you publish on PyPI, you can then easily add your package to the conda-forge ecosystem using the [grayskull](https://conda-forge.org/blog/posts/2020-03-05-grayskull/) tool." +msgstr "" + +#: ../../tutorials/publish-pypi.md:389 +msgid "You will learn how to do that in the next lesson." +msgstr "" + +#: ../../tutorials/publish-pypi.md:396 +msgid "https://docs.python.org/3/library/venv.html" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:1 +msgid "Make your Python package PyPI ready - pyproject.toml" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:3 +msgid "In [the installable code lesson](installable-code), you learned how to add the bare minimum information to a `pyproject.toml` file to make it installable. You then learned how to [publish a bare minimum version of your package to PyPI](publish-pypi.md)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:5 +msgid "Following that you learned how to add a:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:6 +msgid "[README.md](add-readme)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:7 +msgid "[LICENSE](add-license-coc) and" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:8 +msgid "[CODE_OF_CONDUCT](add-coc)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:10 +msgid "to the root of your project directory." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:12 +msgid "To enhance the visibility of your package on PyPI and provide more information about its compatibility with Python versions, project development status, and project maintainers, you should add additional metadata to your `pyproject.toml` file. This lesson will guide you through the process." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:24 +msgid "More about the `pyproject.toml` file and how it's used to store different types of metadata about your package" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:25 +msgid "How to declare information (metadata) about your project to help users find and understand it on PyPI." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:27 +msgid "If you wish to learn more about the `pyproject.toml` format, [check out this page. ](../package-structure-code/pyproject-toml-python-package-metadata.md)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:0 +msgid "Click for lesson takeaways" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:34 +msgid "When creating your pyproject.toml file, consider the following:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:36 +msgid "There are only two required metadata tables that you need to install and publish your Python package:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:37 +msgid "**[build-system]**" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:38 +msgid "**[project]**." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:39 +msgid "The **[project]** table stores your package's metadata. Within the **[project]** table, There are only two _required_ fields:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:40 +msgid "**name=**" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:41 +msgid "**version=**" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:42 +msgid "You should add more metadata to the `[project]` table as it will make it easier for users to find your project on PyPI. And it will also make it easier for installers to understand how to install your package." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:43 +msgid "When you are adding classifiers to the **[project]** table, only use valid values from [PyPI's classifier page](https://PyPI.org/classifiers/). An invalid value here will raise an error when you build and publish your package on PyPI." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:44 +msgid "There is no specific order for tables in the `pyproject.toml` file. However, fields need to be placed within the correct tables. For example `requires =` always need to be in the **[build-system]** table." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:45 +msgid "We suggest that you include your **[build-system]** table at the top of your `pyproject.toml` file." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:50 +msgid "The `pyproject.toml` file is a human and machine-readable file that serves as the primary configuration file for your Python package." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:54 +msgid "[Building your package](build-package) is the step that created the distribution files that are required for you to publish to PyPI." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:58 +msgid "About the .toml format" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:60 +msgid "The **pyproject.toml** file is written in [TOML (Tom's Obvious, Minimal Language) format](https://toml.io/en/). TOML is an easy-to-read structure that is based on key/value pairs. Each section in the **pyproject.toml** file contains a `[table identifier]`. The TOML format can be compared to other structured formats such as`.json`. However, the TOML format was designed to be easier to read for humans." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:62 +msgid "Below you can see the `[build-system]` table. Within that table there are two required key/value pairs." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:65 +msgid "`requires =` is the key and the value is `[\"hatchling\"]` within the `[build-system]` array specified by square brackets `[]`." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:75 +msgid "What is the pyproject.toml used for?" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:77 +msgid "The pyproject.toml file tells your build tool:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:79 +msgid "What build backend to use to build your package (we are using `hatchling` in this tutorial but there are [many others to choose from](/package-structure-code/python-package-build-tools))." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:80 +msgid "How and where to retrieve your package's version:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:81 +msgid "**statically** where you declare the version `version = \"0.1.0\"` or" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:82 +msgid "**dynamically** where the tool looks to the most recent tag in your history to determine the current version." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:83 +msgid "What dependencies your package needs" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:84 +msgid "What versions of Python your package supports (important for your users)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:86 +msgid "The `pyproject.toml` file also makes it easy for anyone browsing your GitHub repository to quickly understand your package's structure such as:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:89 +msgid "How your package is built," +msgstr "" + +#: ../../tutorials/pyproject-toml.md:90 +msgid "What Python versions and operating systems it supports" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:91 +msgid "What it does," +msgstr "" + +#: ../../tutorials/pyproject-toml.md:92 +msgid "Who maintains it" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:94 +msgid "Finally, the pyproject.toml file is also often used to configure tools such as static type checkers (e.g. mypy) and code formatters/linters (e.g. black, ruff)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:97 +msgid "Check out the [PyPA documentation](https://packaging.python.org/en/latest/tutorials/packaging-projects/#choosing-a-build-backend) if you are interested in setting build configurations for other tools." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:99 +msgid "Note that some build tools may deviate in how they store project metadata. As such you may want to refer to their documentation if you decide to use a tool other than Hatch and hatchling. We have selected hatchling and hatch as our tool of choice for this tutorial as it adheres to PyPA rules and guidelines." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:103 +msgid "How is pyproject.toml metadata used?" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:105 +msgid "The pyproject.toml file is the file that your build tool uses to populate a `METADATA` that is included in your Python distribution files that get published to PyPI. This `METADATA` file is then used by PyPI to populate your package's PyPI landing page and help users filter through the tens of thousands of packages published there." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:108 +msgid "Image showing the left side bar of PyPI for the package xclim. The section at the top says Classifier. Below there is a list of items including Development status, intended audience, License, natural language, operating system, programming language and topic. Below each of those sections are various classifier options.\" width=\"300px\">" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:113 +msgid "When you add the classifier section to your pyproject.toml and your package is built, the build tool organizes the metadata into a format that PyPI can understand and represent on your PyPI landing page. These classifiers also allow users to sort through packages by version of python they support, categories and more." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:119 +msgid "A more in-depth overview of pyproject.toml files" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:121 +msgid "[Our guidebook page has a more in depth overview of this file](../package-structure-code/pyproject-toml-python-package-metadata/)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:124 +msgid "How to update your pyproject.toml file" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:126 +msgid "In the last lesson, you created a bare-bones pyproject.toml file that contained the core elements needed to build your package:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:130 +msgid "A `[build-system]` table where you defined your project's backend build tool (`hatchling`)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:131 +msgid "A `[project]` table where you defined your project's version and name." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:133 +msgid "The `pyproject.toml` file that you created, looked like this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:145 +msgid "Your next step is to add additional recommended metadata fields that will both help users find your package on PyPI and also better describe the scope of your package. Once you add this metadata, you don't have to do it again. These metadata fields will only be updated periodically when you do something such as:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:148 +msgid "drop a package dependency" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:149 +msgid "modify what Python versions your package supports." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:151 +msgid "More on hatchling" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:154 +msgid "The documentation for the hatchling back-end is [here](https://hatch.pypa.io/latest/config/metadata/)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:157 +msgid "Step 1: Add Author, maintainer and project description" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:159 +msgid "After completing the [installable code tutorial](installable-code), you should have a pyproject.toml file with a project name and a version in the `[project]` table." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:167 +msgid "Add the following to your table:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:169 +msgid "A **description** of your package. This should be a single line and should briefly describe the goal of your package using non technical terms if as all possible!" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:170 +msgid "package **authors**" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:171 +msgid "package **maintainers**" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:173 +msgid "The `description` is just a string like the other values you've set:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:184 +msgid "When you add authors and maintainers you need to use a format that will look like a Python list with a dictionary within it:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:198 +msgid "Author names & emails" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:202 +msgid "There is a quirk with PyPI for authors that have names but not emails in the pyproject.toml. If you are missing the email for one or more authors or maintainers, like this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:211 +msgid "Then we suggest that you only provide names in your list of names to ensure that everything renders properly on your PyPI page - like this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:220 +msgid "don't have emails for everyone, we suggest that you only add names." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:223 +msgid "Your `pyproject.toml` file now should look like the example below. It is OK if you only have 1 author and the same author is also maintainer of your package:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:0 +msgid "Learn More: What's the difference between author and maintainer in open source?" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:251 +msgid "When adding maintainers and authors, you may want to think about the difference between the two." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:253 +msgid "Authors generally include people who:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:254 +msgid "originally created / designed developed the package and" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:255 +msgid "people who add new functionality to the package." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:257 +msgid "Whereas maintainers are the people that are currently, actively working on the project. It is often the case that there is overlap in authors and maintainers. As such these lists may be similar or the same." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:259 +msgid "A good example of when the lists might diverge is sometimes you have a package where an initial author developed it and then stepped down as a maintainer to move on to other things. This person may continue to be considered an author but no longer actively maintains the package." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:261 +msgid "It is important to note that there are many ways to define author vs maintainer and we don't prescribe a single approach in this tutorial." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:263 +msgid "However, we encourage you to consider carefully, for PyPI publication, who you want to have listed as authors and maintainers on your PyPI landing page." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:267 +msgid "Step 2: Add README and license" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:269 +msgid "In the previous lessons, you added both a [README.md](add-readme) file and a [LICENSE](add-license-coc) to your package repository. Once you have those files, you can add them to your pyproject.toml file as links following the example below." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:297 +msgid "Step 3: Specify Python version with `requires-python`" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:299 +msgid "Add the `requires-python` field to your `pyproject.toml` `[project]` table. The `requires-python` field helps pip identify which Python versions that your package supports. It is set to a single value. The [packaging specification](https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata-requires-python) defines`requires-python` as a string that uses version specifiers. Most projects will specify the oldest Python version supported by the package. In some advanced cases, an upper bound is set to indicate which future Python versions, if any, will be supported." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:331 +msgid "Step 4: Specify Dependencies" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:333 +msgid "Next add your dependencies table to the project table. The `dependencies =` section contains a list (or array in the toml language) of the Python packages that your package requires to run properly in a Python environment. Similar to the requirements listed in the `[build-system]` table above:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:341 +msgid "dependencies are added in an array (similar to a Python list) structure." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:347 +msgid "A dependency can be limited to specific versions using a **version specifier.** If the dependency has no version specifier after the dependency name, your package can use any version of the dependent package. Code changes over time, bugs are fixed, APIs change, and so it's good to be clear about which version of the dependency you wrote your code to be compatible with - a package you wrote this year probably isn't compatible with numpy v0.0.1!" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:351 +msgid "[Learn more about various ways to specify ranges of package versions here.](https://packaging.python.org/en/latest/specifications/version-specifiers/#id5)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:353 +msgid "The most common version specifier is a **lower bound,** allowing any version higher than the specified version. Ideally you should set this to the lowest version that is still compatible with your package, but in practice for new packages this is often set at the version that was current at the time the package was written[^lowerbound]." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:358 +msgid "Lower bounds look like this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:364 +msgid "Commas are used to separate individual dependencies, and each package in your `dependencies` section can use different types of version specifiers:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:375 +msgid "Your `pyproject.toml` file will now look like this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:405 +msgid "Pin dependencies with caution" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:406 +msgid "\"Pinning\" a dependency means setting it to a specific version, like this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:408 +msgid "`numpy == 1.0`." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:410 +msgid "If you are building a library package that other developers will depend upon, you must be cautious before pinning to a precise dependency version. Applications, such as production websites, will often pin their dependencies since other packages will not depend on their project. This is because users will be installing your package into various environments. A dependency pinned to a single specific version can make resolving a Python environment more challenging. As such only pin dependencies to a specific version if you absolutely need to do so." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:418 +msgid "Similarly, you should be cautious when specifying an upper bound on a package. These two specifications are equivalent:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:426 +msgid "One build tool that you should be aware of that pins dependencies to an upper bound by default is Poetry. [Read more about how to safely add dependencies with Poetry, here.](challenges-with-poetry)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:429 +msgid "Step 5: Add PyPI classifiers" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:431 +msgid "Next you will add classifiers to your `pyproject.toml` file. The value for each classifier that you add to your `pyproject.toml` file must come from the list of [PyPI accepted classifier values found here](https://PyPI.org/classifiers/). Any deviations in spelling and format will cause issues when you publish to PyPI." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:433 +msgid "What happens when you use incorrect classifiers?" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:436 +msgid "If you do not [use standard classifier values](https://PyPI.org/classifiers/), when you try to publish your package on PyPI it will be rejected. 😔 Don't worry if PyPI rejects you on your first try! It has happened to all of us." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:439 +msgid "Review that list and add items below to your `pyproject.toml` file:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:441 +msgid "development status" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:442 +msgid "intended audiences" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:443 +msgid "topic" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:444 +msgid "license and" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:445 +msgid "programming language support" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:447 +msgid "The classifier key should look something like the example below. A few notes:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:449 +msgid "Your classifier values might be different depending upon the license you have selected for your package, your intended audience, development status of your package and the Python versions that you support" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:450 +msgid "You can add as many classifiers as you wish as long as you use the [designated PyPI classifier values](https://PyPI.org/classifiers/)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:490 +msgid "Note that while classifiers are not required in your `pyproject.toml` file, they will help users find your package. As such we strongly recommend that you add them." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:492 +msgid "Step 6: Add the `[project.urls]` table" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:494 +msgid "Finally, add the project.urls table to your pyproject.toml file." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:496 +msgid "`project.urls` contains links that are relevant for your project. You might want to include:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:498 +msgid "**Homepage:** A link to your published documentation for your project. If you are working through this tutorial, then you may not have this link yet. That's ok, you can skip it for the time being." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:499 +msgid "**Bug reports:** a link to your issues / discussions or wherever you want users to report bugs." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:500 +msgid "**Source:** the GitHub / GitLab link for your project." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:546 +msgid "There are many other urls that you can add here. Check out the [README file here for an overview](https://github.com/patrick91/links-demo)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:549 +msgid "Putting it all together - your completed pyproject.toml file" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:551 +msgid "Below is an example of a complete `pyproject.toml` file that is commented with all of the sections we discussed above." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:0 +msgid "Appendix - Click for a fully commented pyproject.toml file" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:601 +msgid "Below is a fully commented pyproject.toml file if you want to use it for reference." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:666 +msgid "Example `pyproject.toml` files" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:668 +msgid "Below are some examples of `pyproject.toml` files from various packages in the scientific and pyOpenSci ecosystem." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:669 +msgid "[PyPA's fully documented example pyproject.toml file](https://github.com/pypa/sampleproject/blob/main/pyproject.toml)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:670 +msgid "[taxpasta has a nicely organized pyproject.toml file and is a pyOpenSci approved package](https://github.com/taxprofiler/taxpasta/blob/f9f6eea2ae7dd08bb60a53dd49ad77e4cf143573/pyproject.toml)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:676 +msgid "At this point you've created:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:678 +msgid "A [README.md](add-readme) file for your package" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:679 +msgid "A [CODE_OF_CONDUCT.md](add-coc) file to support your user community" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:680 +msgid "And a [LICENSE](add-license-coc) file which provides legal boundaries around how people can and can't use your software" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:682 +msgid "You also learned [how to publish your package to (test)PyPI](publish-pypi)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:684 +msgid "Publish a new version of your package to PyPI" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:686 +msgid "You are now ready to publish a new version of your Python package to (test) PyPI. When you do this you will see that the landing page for your package now contains a lot more information." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:688 +msgid "Try to republish now." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:690 +msgid "First, update the version of your package in your pyproject toml file. Below version is updated from `0.1` to `0.1.1`." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:703 +msgid "Now use hatch to publish the new version of your package to test.PyPI.org." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:710 +msgid "Next (optional) step - publishing to conda-forge" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:712 +msgid "You now have all of the skills that you need to publish your package to PyPI." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:715 +msgid "If you also want to publish your package on conda-forge (which is a channel within the conda ecosystem), you will learn how to do that in the next lesson." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:719 +msgid "Really good resources from jeremiah https://daniel.feldroy.com/posts/2023-08-pypi-project-urls-cheatsheet useful (and the linked links-demo even more so)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:356 +msgid "Some packaging tools will do this for you when you add a dependency using their cli interface. For example [`poetry add`](https://python-poetry.org/docs/cli/#add) will add the most recent version with a `^` specifier, and [`pdm add`](https://pdm-project.org/latest/reference/cli/#add) will add the most recent version with `>=`." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:1 +msgid "Using Hatch to Migrate setup.py to a pyproject.toml" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:3 +msgid "Hatch can be particularly useful to generate your project's `pyproject.toml` if your project already has a `setup.py`." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:5 +msgid "Note" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:8 +msgid "This step is not necessary and is only useful if your project already has a `setup.py` file defined." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:9 +msgid "If your project does not already define a `setup.py` see [Make your Python code installable](installable-code.md)" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:17 +msgid "The process of using Hatch to transition to using `pyproject.toml` for projects that already have a `setup.py` defined." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:20 +msgid "What is Hatch?" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:22 +msgid "Hatch is a Python package manager designed to streamline the process of creating, managing, and distributing Python packages. It provides a convenient CLI (Command-Line Interface) for tasks such as creating new projects, managing dependencies, building distributions, and publishing packages to repositories like PyPI." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:28 +msgid "See [Get to know Hatch](get-to-know-hatch.md) for more information." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:31 +msgid "Prerequisites" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:33 +msgid "Before we begin, ensure that you have Hatch installed on your system. You can install it via pip:" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:39 +msgid "Sample Directory Tree" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:41 +msgid "Let's take a look at a sample directory tree structure before and after using `hatch init`:" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:43 +msgid "Before `hatch init`" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:59 +msgid "After `hatch init`" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:77 +msgid "As you can see, the main change after running `hatch init` is the addition of the `pyproject.toml` file in the project directory." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:79 +msgid "Step-by-Step Guide" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:81 +msgid "Now, let's walk through the steps to use Hatch to create a `pyproject.toml` file for your project." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:83 +msgid "**Navigate to Your Project Directory**: Open your terminal or command prompt and navigate to the directory where your Python project is located." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:85 +msgid "**Initialize Hatch**: Run the following command to initialize Hatch in your project directory:" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:91 +msgid "**Review and Customize**: After running the previous command, Hatch will automatically generate a `pyproject.toml` file based on your existing project configuration. Take some time to review the contents of the generated `pyproject.toml` file. You may want to customize certain settings or dependencies based on your project's requirements (see [pyproject.toml tutorial](pyproject-toml.md) for more information about the `pyproject.toml`)." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:93 +msgid "**Verify**: Verify that the `pyproject.toml` file accurately reflects your project configuration and dependencies. You can manually edit the file if needed, but be cautious and ensure that the syntax is correct." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:95 +msgid "**Delete setup.py**: Since we're migrating to using `pyproject.toml` exclusively, the `setup.py` file becomes unnecessary. You can safely delete it from your project directory." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:97 +msgid "**Test Build**: Before proceeding further, it's essential to ensure that your project builds successfully using only the `pyproject.toml` file. Run the following command to build your project:" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:103 +msgid "This command will build your project based on the specifications in the `pyproject.toml` file. Make sure to check for any errors or warnings during the build process." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:105 +msgid "**Test Existing Functionality**: After successfully building your project with `pyproject.toml`, it's crucial to ensure that your project's existing functionality remains intact. Run any pre-existing tests to verify that everything still works as expected." +msgstr "" +