diff --git a/.github/workflows/crowdin_sync.yml b/.github/workflows/crowdin_sync.yml index ca44e519..bf4caca7 100644 --- a/.github/workflows/crowdin_sync.yml +++ b/.github/workflows/crowdin_sync.yml @@ -2,6 +2,9 @@ name: Crowdin Sync on: workflow_dispatch: + push: + branches: + - translation2 jobs: sync-translations: @@ -21,7 +24,7 @@ jobs: create_pull_request: true pull_request_title: "Crowdin: New translations" pull_request_body: "Crowdin synced updated translations via GitHub Action." - pull_request_base_branch_name: "main" + pull_request_base_branch_name: "translation2" env: GITHUB_TOKEN: ${{ secrets.GH_TOKEN_CROWDIN }} CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }} 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 "" + diff --git a/locales/templates/LC_MESSAGES/CONTRIBUTING.pot b/locales/templates/LC_MESSAGES/CONTRIBUTING.pot new file mode 100644 index 00000000..b6c6a643 --- /dev/null +++ b/locales/templates/LC_MESSAGES/CONTRIBUTING.pot @@ -0,0 +1,513 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2025, pyOpenSci +# This file is distributed under the same license as the pyOpenSci Python Package Guide package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: pyOpenSci Python Package Guide \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-04-30 18:44-0600\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../CONTRIBUTING.md:4 +msgid "Contributing to the Python Packaging Guide" +msgstr "" + +#: ../../CONTRIBUTING.md:6 +msgid "The guide is a community resource." +msgstr "" + +#: ../../CONTRIBUTING.md:8 +msgid "TL;DR" +msgstr "" + +#: ../../CONTRIBUTING.md:10 +msgid "We welcome contributions in the form of issues and pull requests:" +msgstr "" + +#: ../../CONTRIBUTING.md:12 +msgid "If you have an idea for something that should be included in the guide, [please open an issue here](https://github.com/pyOpenSci/python-package-guide/issues)." +msgstr "" + +#: ../../CONTRIBUTING.md:13 +msgid "If you find a typo, feel free to [submit a pull request](https://github.com/pyOpenSci/python-package-guide/pulls) to modify the text directly. Or, if you are less comfortable with pull requests, feel free to open an issue." +msgstr "" + +#: ../../CONTRIBUTING.md:14 +msgid "If you are interested in helping translate the guide into other languages, take a look at the [translation guide](./TRANSLATING.md)." +msgstr "" + +#: ../../CONTRIBUTING.md:15 +msgid "If you want to see a larger change to the content of the guide book, please submit an issue first!" +msgstr "" + +#: ../../CONTRIBUTING.md:17 +msgid "If you are unsure about how to contribute or are not familiar with git and github, this guide will help you through the process." +msgstr "" + +#: ../../CONTRIBUTING.md:19 +msgid "How the Python Packaging Guide is structured" +msgstr "" + +#: ../../CONTRIBUTING.md:21 +msgid "The Python Packaging Guide is written in myST (a variant of MarkDown and rST) and we use **Sphinx**, a documentation engine built in `Python` to build the HTML version you see online." +msgstr "" + +#: ../../CONTRIBUTING.md:23 +msgid "We use a tool called Nox to manage the process of building the guide." +msgstr "" + +#: ../../CONTRIBUTING.md:25 +msgid "Two approaches to contributing" +msgstr "" + +#: ../../CONTRIBUTING.md:27 +msgid "You can contribute to the guide using two approaches." +msgstr "" + +#: ../../CONTRIBUTING.md:29 +msgid "The first approach is using a local copy of the guide in your computer. This option requires a more involved setup, but allows you to build the guide locally to verify your contribution did not introduce any bugs before submitting a pull request. It is the recommended approach for larger contribution, like writing a whole new section." +msgstr "" + +#: ../../CONTRIBUTING.md:31 +msgid "The second approach is making your contribution directly in the GitHub website. This option does not require any setup on your computer and while your contribution will still be tested when you submit a PR (continuous integration), it will take longer for you to get any feedback in case of issue. It is the best way to make small contribution, like fixing typos, or if this is your first contribution to open source and the first approach feels too intimidating." +msgstr "" + +#: ../../CONTRIBUTING.md:33 +msgid "Forking the repository" +msgstr "" + +#: ../../CONTRIBUTING.md:35 +msgid "Independently of the approach you choose, the first step is to fork the Python Packaging Guide repository into your personal GitHub space. You can do this by clicking the \"Fork\" button in the top right corner of the repository page." +msgstr "" + +#: ../../CONTRIBUTING.md:38 +msgid "[Learn more: Fork and Clone GitHub Repos](https://datascienceskills.org/lessons/git-github/git-intro/3-fork-clone/) is a good resource to learn more about forking." +msgstr "" + +#: ../../CONTRIBUTING.md:40 +msgid "To fork a repo," +msgstr "" + +#: ../../CONTRIBUTING.md:42 +msgid "Make sure you are logged into GitHub." +msgstr "" + +#: ../../CONTRIBUTING.md:44 +msgid "Go to the repo you would like to fork, in this case the [Python Packaging Guide](https://www.github.com/pyopensci/python-package-guide) repo." +msgstr "" + +#: ../../CONTRIBUTING.md:46 +msgid "In the top right-hand corner of the page there is a 'Fork' button. Click that button. You will be brought to a new page where you will 'Create a new fork'. Feel free to keep all the default inputs and click 'Create fork'. This will create a copy of the repo at `https://github.com//python-package-guide`, where `` is your GitHub username." +msgstr "" + +#: ../../CONTRIBUTING.md:51 +msgid "Contributing via the GitHub website" +msgstr "" + +#: ../../CONTRIBUTING.md:53 +msgid "How to edit a MarkDown file" +msgstr "" + +#: ../../CONTRIBUTING.md:55 +msgid "The Python Packaging Guide is written in myST, a variant of MarkDown. You can edit the files directly in the GitHub website. To do so, navigate to the file you want to edit and click the pencil icon in the top right corner of the file." +msgstr "" + +#: ../../CONTRIBUTING.md:58 +msgid "Edit button in GitHub" +msgstr "" + +#: ../../CONTRIBUTING.md:64 +msgid "An image showing how to edit a file in GitHub. The pencil icon is highlighted with a red rectangle." +msgstr "" + +#: ../../CONTRIBUTING.md:66 +msgid "Edit file in GitHub" +msgstr "" + +#: ../../CONTRIBUTING.md:72 +msgid "An image showing when a file is being edited in GitHub. The file content is displayed in a text editor." +msgstr "" + +#: ../../CONTRIBUTING.md:75 +msgid "To preview your changes, click the \"Preview changes\" tab." +msgstr "" + +#: ../../CONTRIBUTING.md:77 +msgid "Preview changes in GitHub" +msgstr "" + +#: ../../CONTRIBUTING.md:83 +msgid "An image showing how to preview changes in GitHub. The file content is displayed in a text editor. The preview changes tab is highlighted with a red rectangle." +msgstr "" + +#: ../../CONTRIBUTING.md:86 +msgid "How to commit your changes" +msgstr "" + +#: ../../CONTRIBUTING.md:88 +msgid "When you are done editing the file, scroll down to the bottom of the page. You will see a section called \"Commit changes\". Here you can write a title and a description for your changes. Make sure to write a clear and concise title that describes the changes you made." +msgstr "" + +#: ../../CONTRIBUTING.md:91 +msgid "Commit changes in GitHub" +msgstr "" + +#: ../../CONTRIBUTING.md:97 +msgid "An image showing how to commit changes in GitHub. The commit message is displayed in a text editor. The commit changes section is highlighted with a red rectangle." +msgstr "" + +#: ../../CONTRIBUTING.md:100 +msgid "After writing your commit message, click the \"Commit changes\" button to save your changes." +msgstr "" + +#: ../../CONTRIBUTING.md:102 +msgid "Contributing locally on your computer" +msgstr "" + +#: ../../CONTRIBUTING.md:104 +msgid "Clone your forked repository" +msgstr "" + +#: ../../CONTRIBUTING.md:106 +msgid "To clone your forked repository to your computer, you need to copy the URL of your forked repository and run the following command in your terminal:" +msgstr "" + +#: ../../CONTRIBUTING.md:111 +msgid "Replace `` with the URL of your forked repository. You can find the URL by clicking the green \"Code\" button on your forked repository page." +msgstr "" + +#: ../../CONTRIBUTING.md:113 +msgid "Clone repository in GitHub" +msgstr "" + +#: ../../CONTRIBUTING.md:119 +msgid "An image showing how to clone a repository in GitHub. The URL of the repository is displayed in a text editor. The code button is highlighted with a red rectangle." +msgstr "" + +#: ../../CONTRIBUTING.md:122 +msgid "Create a new branch" +msgstr "" + +#: ../../CONTRIBUTING.md:124 +msgid "Before making any changes, you should create a new branch to work on. This will help keep your changes separate from the main branch and make it easier to submit a pull request." +msgstr "" + +#: ../../CONTRIBUTING.md:126 +msgid "To create a new branch, run the following command in your terminal:" +msgstr "" + +#: ../../CONTRIBUTING.md:132 +msgid "Create a virtual environment" +msgstr "" + +#: ../../CONTRIBUTING.md:134 +msgid "To build the guide locally, you need to create a virtual environment and install the dependencies. You can do this by running the following commands in your terminal:" +msgstr "" + +#: ../../CONTRIBUTING.md:136 +msgid "**On Windows**:" +msgstr "" + +#: ../../CONTRIBUTING.md:142 +msgid "**On MacOS and Linux**:" +msgstr "" + +#: ../../CONTRIBUTING.md:148 +msgid "Install the development dependencies" +msgstr "" + +#: ../../CONTRIBUTING.md:150 +msgid "To install the development dependencies, run the following command in your terminal:" +msgstr "" + +#: ../../CONTRIBUTING.md:156 +msgid "Commit your changes" +msgstr "" + +#: ../../CONTRIBUTING.md:158 +msgid "After making your changes, you need to commit them to your local repository. To do this, run the following commands in your terminal:" +msgstr "" + +#: ../../CONTRIBUTING.md:160 +msgid "To see the changes you made:" +msgstr "" + +#: ../../CONTRIBUTING.md:164 +msgid "To add the changes to the staging area:" +msgstr "" + +#: ../../CONTRIBUTING.md:168 +msgid "To commit the changes:" +msgstr "" + +#: ../../CONTRIBUTING.md:172 +msgid "Replace `\"Your commit message here\"` with a clear and concise message that describes the changes you made." +msgstr "" + +#: ../../CONTRIBUTING.md:174 +msgid "How to build the guide locally" +msgstr "" + +#: ../../CONTRIBUTING.md:176 +msgid "To build the guide locally, you can use the `nox` command. This will run the default `nox` session, which builds the guide and opens it in your browser." +msgstr "" + +#: ../../CONTRIBUTING.md:178 +msgid "To see the different sessions available, you can run the following command in your terminal:" +msgstr "" + +#: ../../CONTRIBUTING.md:183 +msgid "There are different sessions in nox related to building the docs: `docs`, `docs-test`, `docs-live`. You can run them by specifying the session name after the `nox` command." +msgstr "" + +#: ../../CONTRIBUTING.md:185 +msgid "`docs`: this session builds the guide and opens it in your browser." +msgstr "" + +#: ../../CONTRIBUTING.md:189 +msgid "To see the guide built locally, open the file `_build/html/index.html` in your browser." +msgstr "" + +#: ../../CONTRIBUTING.md:191 +msgid "`docs-test`: this session runs the tests for the guide." +msgstr "" + +#: ../../CONTRIBUTING.md:195 +msgid "If the tests fail, you will see an error message in your terminal. You need to fix the errors before submitting your pull request." +msgstr "" + +#: ../../CONTRIBUTING.md:197 +msgid "`docs-live`: this session builds the guide and opens it in your browser with live reloading." +msgstr "" + +#: ../../CONTRIBUTING.md:201 +msgid "open the local version of the guide in your browser at ``localhost`` shown in the terminal." +msgstr "" + +#: ../../CONTRIBUTING.md:203 +msgid "Before you submit your pull request" +msgstr "" + +#: ../../CONTRIBUTING.md:205 +msgid "Before submitting your pull request, make sure to run the tests and check the formatting of your code." +msgstr "" + +#: ../../CONTRIBUTING.md:210 +msgid "If the tests fail, you will see an error message in your terminal. You need to fix the errors before submitting your pull request. Also make sure to check the formatting of your documentation by building the docs locally and checking that your changes look correct." +msgstr "" + +#: ../../CONTRIBUTING.md:214 +msgid "Submitting a pull request with your contribution" +msgstr "" + +#: ../../CONTRIBUTING.md:216 +msgid "How to make a pull request" +msgstr "" + +#: ../../CONTRIBUTING.md:218 +msgid "To open a pull request on GitHub, navigate to the main page of your forked repository and click on the \"Pull requests\" tab." +msgstr "" + +#: ../../CONTRIBUTING.md:220 +msgid "Pull requests tab in GitHub" +msgstr "" + +#: ../../CONTRIBUTING.md:226 +msgid "An image showing how to navigate to the pull requests tab in GitHub. The pull requests tab is highlighted with a red rectangle." +msgstr "" + +#: ../../CONTRIBUTING.md:229 +msgid "Click on the \"New pull request\" button." +msgstr "" + +#: ../../CONTRIBUTING.md:231 +msgid "New pull request button in GitHub" +msgstr "" + +#: ../../CONTRIBUTING.md:237 +msgid "An image showing how to create a new pull request in GitHub. The new pull request button is highlighted with a red rectangle." +msgstr "" + +#: ../../CONTRIBUTING.md:240 +msgid "Write a clear and concise title and description for your pull request. Make sure to describe the changes you made and why they are necessary." +msgstr "" + +#: ../../CONTRIBUTING.md:242 +msgid "What happens when you submit a pull request (CI/CD)" +msgstr "" + +#: ../../CONTRIBUTING.md:244 +msgid "Once you submit a pull request, a series of checks will be run to ensure that your changes do not introduce any bugs or errors. These checks include:" +msgstr "" + +#: ../../CONTRIBUTING.md:246 +msgid "**Code formatting and styles**: checks that your code is formatted correctly, by `pre-commit.ci - pr check`." +msgstr "" + +#: ../../CONTRIBUTING.md:247 +msgid "**docs build**: checks that the documentation builds correctly, using `circleci`." +msgstr "" + +#: ../../CONTRIBUTING.md:249 +msgid "You will see the status of these checks in your pull request." +msgstr "" + +#: ../../CONTRIBUTING.md:251 +msgid "Pull request checks in GitHub" +msgstr "" + +#: ../../CONTRIBUTING.md:257 +msgid "An image showing the status of the checks in a pull request in GitHub. The checks are displayed in a table with a status icon next to each check. The checks are highlighted with a red rectangle." +msgstr "" + +#: ../../CONTRIBUTING.md:259 +msgid "If any of these checks fail, you will see an error message in your pull request. You need to fix the errors before your changes can be merged." +msgstr "" + +#: ../../CONTRIBUTING.md:261 +msgid "Pull request checks failed in GitHub" +msgstr "" + +#: ../../CONTRIBUTING.md:267 +msgid "An image showing the status of the checks in a pull request in GitHub. The checks are displayed in a table with a status icon next to each check. The checks that failed and the details link are highlighted with a red rectangle." +msgstr "" + +#: ../../CONTRIBUTING.md:270 +msgid "To get more information about the errors, you can click on the \"Details\" link next to the failed check." +msgstr "" + +#: ../../CONTRIBUTING.md:272 +msgid "What to expect from the review process" +msgstr "" + +#: ../../CONTRIBUTING.md:274 +msgid "Once you submit a pull request, a maintainer of the repository will review your changes and provide feedback. The review process may involve:" +msgstr "" + +#: ../../CONTRIBUTING.md:276 +msgid "**Comments**: the reviewer may leave comments on your pull request to ask questions or provide feedback." +msgstr "" + +#: ../../CONTRIBUTING.md:277 +msgid "**Suggestions**: the reviewer may suggest changes to your code or documentation." +msgstr "" + +#: ../../CONTRIBUTING.md:278 +msgid "**Approvals**: once the reviewer is satisfied with your changes, they will approve the pull request." +msgstr "" + +#: ../../CONTRIBUTING.md:280 +msgid "You can make changes to your pull request by pushing new commits to the branch. The pull request will be updated automatically with your new changes." +msgstr "" + +#: ../../CONTRIBUTING.md:282 +msgid "Once your pull request is approved, it will be merged into the main branch and your changes will be included in the guide." +msgstr "" + +#: ../../CONTRIBUTING.md:284 +msgid "Additional help" +msgstr "" + +#: ../../CONTRIBUTING.md:286 +msgid "How to get help" +msgstr "" + +#: ../../CONTRIBUTING.md:288 +msgid "*__TODO__: This section should describe the options for finding more help in case beginner contributors need more help (e.g., create an issue, post in a forum, etc).*" +msgstr "" + +#: ../../CONTRIBUTING.md:290 +msgid "Additional resources" +msgstr "" + +#: ../../CONTRIBUTING.md:292 +msgid "*__TODO__: It should also include links to beginner documentation, like the GitHub docs.*" +msgstr "" + +#: ../../CONTRIBUTING.md:294 +msgid "Annex" +msgstr "" + +#: ../../CONTRIBUTING.md:296 +msgid "Code examples" +msgstr "" + +#: ../../CONTRIBUTING.md:298 +msgid "This guide uses the [literalinclude Sphinx directive](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-literalinclude) whenever possible to keep code and prose separate. Code for use in the documentation is kept in the `examples/` folder." +msgstr "" + +#: ../../CONTRIBUTING.md:302 +msgid "Referencing code in documentation" +msgstr "" + +#: ../../CONTRIBUTING.md:304 +msgid "If an example is present elsewhere in the documentation that you want to use, you can copy the `literalinclude` directive verbatim and the examples will stay in sync." +msgstr "" + +#: ../../CONTRIBUTING.md:307 +msgid "If you already see code in the examples folder that you can use for new documentation, a new `literalinclude` can be made to extract it into the site. Only a relative path to the code is required for a working `literalinclude`, but you should in almost all cases also provide a `:language:` and `:lines:`. The former makes code examples prettier, and the later can protect your example from future modifications to the code." +msgstr "" + +#: ../../CONTRIBUTING.md:312 +msgid "**Pro tip**: As an alternative to `:lines:` there are also the `:start-after:`, `:start-at:`, `:end-before:`, and `:end-at:` options. And if the example code is Python, `:pyobject:` can be an even more future-proof way to keep the same documentation content even through code refactors." +msgstr "" + +#: ../../CONTRIBUTING.md:316 +msgid "If you need example code that doesn't yet exist in `examples/` see [creating code for documentation](#creating-code-for-documentation)." +msgstr "" + +#: ../../CONTRIBUTING.md:319 +msgid "Creating code for documentation" +msgstr "" + +#: ../../CONTRIBUTING.md:321 +msgid "Whenever you come across a place that could benefit from a code block, instead of writing it in-line with a code fence (`` ``` `` blocked text) you can write it as a file in its own format. Your example may even already exist; [see referencing code in documentation ](#referencing-code-in-documentation)." +msgstr "" + +#: ../../CONTRIBUTING.md:325 +msgid "If you want to add a new example that doesn't fit into any of the existing example files, you can create a new file and reference it in a `literalinclude` block. If it makes sense for that file to live within one of the existing example projects please add it there; otherwise create a new folder in the `examples` directory." +msgstr "" + +#: ../../CONTRIBUTING.md:329 +msgid "If an existing example is incomplete or a new example makes sense to be added to an existing file, go ahead and add it, but take care to not break the rest of the guide. Whenever possible, extend the example rather that rewrite it. So for instance, add new functions to the end of the file, new methods after all existing ones in a class." +msgstr "" + +#: ../../CONTRIBUTING.md:333 +msgid "Example code is checked for correctness, so adding a new example may require adding additional tests for coverage, and will require fixing any failing tests." +msgstr "" + +#: ../../CONTRIBUTING.md:336 +msgid "***⚠️ WARNING***: great care should be taken when modifying existing example code, especially any modification beyond appending to the end of the file. All code examples are (potentially) shared examples. This makes for more consistent examples in the guide but can mean action-at-a-distance when modifying the examples for one particular use case. If you find yourself modifying existing examples try running this command and then checking those pages in a new build." +msgstr "" + +#: ../../CONTRIBUTING.md:344 +msgid "Example:" +msgstr "" + +#: ../../CONTRIBUTING.md:346 +msgid "Instead of writing example code in markdown like this" +msgstr "" + +#: ../../CONTRIBUTING.md:357 +msgid "The python can be extracted into a `.py` file" +msgstr "" + +#: ../../CONTRIBUTING.md:371 +msgid "As another example, if you only need to show part of a `pyproject.toml`, we already have complete project definitions, you need only to find the relevant part." +msgstr "" + +#: ../../CONTRIBUTING.md:374 +msgid "Instead of writing this" +msgstr "" + +#: ../../CONTRIBUTING.md:386 +msgid "an example could be extracted from an existing toml file" +msgstr "" diff --git a/locales/templates/LC_MESSAGES/TRANSLATING.pot b/locales/templates/LC_MESSAGES/TRANSLATING.pot new file mode 100644 index 00000000..a86961a6 --- /dev/null +++ b/locales/templates/LC_MESSAGES/TRANSLATING.pot @@ -0,0 +1,450 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2025, pyOpenSci +# This file is distributed under the same license as the pyOpenSci Python Package Guide package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: pyOpenSci Python Package Guide \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-04-30 18:44-0600\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../TRANSLATING.md:5 +msgid "Translation Guide for the Python Packaging Guide" +msgstr "" + +#: ../../TRANSLATING.md:7 +msgid "This guide will help you get started contributing to the translation of the Python Packaging Guide." +msgstr "" + +#: ../../TRANSLATING.md:9 +msgid "The process of contributing to the translation of the guide is similar to the process of contributing to the guide itself, except that instead of working on the guide source files directly, you will be working on the translation files." +msgstr "" + +#: ../../TRANSLATING.md:11 +msgid "Overview of the Translation Process" +msgstr "" + +#: ../../TRANSLATING.md:13 +msgid "The process of adapting software to different languages is called internationalization, or i18n for short. Internationalization makes sure that translation can happen without having to modify the source code, or in our case, the original English source files of the guide." +msgstr "" + +#: ../../TRANSLATING.md:15 +msgid "Sphinx, the documentation engine we use to build the Python Package Guide, has built-in support for internationalization, so the workflow is very straightforward." +msgstr "" + +#: ../../TRANSLATING.md:17 +msgid "The process of actually translating the guide into different languages is called localization, or l10n for short. This is the step you will be helping with your contribution." +msgstr "" + +#: ../../TRANSLATING.md:19 +msgid "Here is a quick overview of how the translation process works:" +msgstr "" + +#: ../../TRANSLATING.md:21 +msgid "The guide is originally written in English and stored in a set of MarkDown files." +msgstr "" + +#: ../../TRANSLATING.md:22 +msgid "The source files are processed by Sphinx to generate a set of translation files stored in a folder for each target language." +msgstr "" + +#: ../../TRANSLATING.md:23 +msgid "Contributors (like you!) translate these files into the different languages." +msgstr "" + +#: ../../TRANSLATING.md:24 +msgid "When the guide is built, Sphinx creates a version of the guide in the original language (English) and the translated versions for the languages defined in the configuration." +msgstr "" + +#: ../../TRANSLATING.md:27 +msgid "You don't need to understand the technical details to contribute, but if you are interested in learning how Sphinx handles internationalization and localization, you can find more information [here](https://www.sphinx-doc.org/en/master/usage/advanced/intl.html)." +msgstr "" + +#: ../../TRANSLATING.md:30 +msgid "Setting up Your Local Environment" +msgstr "" + +#: ../../TRANSLATING.md:32 +msgid "Before you start, you will need to set up your local work environment." +msgstr "" + +#: ../../TRANSLATING.md:34 +msgid "First, fork the guide repository into your personal GitHub account and clone the forked repository to your local computer." +msgstr "" + +#: ../../TRANSLATING.md:36 +msgid "To create a virtual environment and install the development dependencies for the guide, run the following commands:" +msgstr "" + +#: ../../TRANSLATING.md:45 +msgid "TODO: This section needs more work or to be replaced with a reference to the CONTRIBUTING guide." +msgstr "" + +#: ../../TRANSLATING.md:47 +msgid "Starting a New Language Translation" +msgstr "" + +#: ../../TRANSLATING.md:49 +msgid "If you plan to work on an existing translation, you can skip this step and go directly to the next section." +msgstr "" + +#: ../../TRANSLATING.md:51 +#: ../../TRANSLATING.md:217 +msgid "Important" +msgstr "" + +#: ../../TRANSLATING.md:52 +msgid "If you would like to start the translation of the guide into a new language, start by [creating an issue](https://github.com/pyOpenSci/python-package-guide/issues) in the repository." +msgstr "" + +#: ../../TRANSLATING.md:55 +msgid "To generate the translation files for a new language, add the language to the `LANGUAGES` list in the `noxfile.py` configuration file. [Nox](https://nox.thea.codes/en/stable/index.html) is the tool we use to manage the building of the guide and its translations." +msgstr "" + +#: ../../TRANSLATING.md:57 +msgid "Inside `noxfile.py`, find the `LANGUAGES` list and add the corresponding two-letter code. For example, if you want to start the translation of the guide into French, you would add `'fr'`:" +msgstr "" + +#: ../../TRANSLATING.md:68 +msgid "You can find a list of the two-letter Sphinx language option [here](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language)." +msgstr "" + +#: ../../TRANSLATING.md:71 +msgid "Preparing the Translation Files" +msgstr "" + +#: ../../TRANSLATING.md:73 +msgid "The translation files contain the original English text and a space for you to enter the translated text. Before starting to translate, you need to make sure the translation files are up to date with the latest changes to the guide." +msgstr "" + +#: ../../TRANSLATING.md:75 +msgid "You can do this by running the following command, replacing LANG by the language code you plan to work on (e.g., `es` for Spanish):" +msgstr "" + +#: ../../TRANSLATING.md:81 +msgid "This command will create the translation files if they don't exist yet, or update them with the latest changes if they already exist." +msgstr "" + +#: ../../TRANSLATING.md:83 +msgid "The translation files are text files with the `.po` extension stored in the `./locales`, in folders corresponding to each language. For example, the translation files for Spanish are stored in the `locale/es/LC_MESSAGES` directory." +msgstr "" + +#: ../../TRANSLATING.md:85 +msgid "Because the translation files map the original English text to translated text, they are sometimes referred to as \"catalog\" files or \"portable object\" files." +msgstr "" + +#: ../../TRANSLATING.md:88 +msgid "You don't need to know all the details about the PO format in order to translate. If you are interested in learning more, you can find additional details in the [GNU gettext documentation](https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html)." +msgstr "" + +#: ../../TRANSLATING.md:91 +msgid "Working on a Translation" +msgstr "" + +#: ../../TRANSLATING.md:93 +msgid "In order to start translating, go to the folder inside `./locales` corresponding to the target language you want to translate to (for example, `./locale/es/LC_MESSAGES/` for the Spanish translation)." +msgstr "" + +#: ../../TRANSLATING.md:95 +msgid "In this folder you will find a set of `.po` files, corresponding to the different sections of the guide:" +msgstr "" + +#: ../../TRANSLATING.md:111 +msgid "You may also see some `.mo` files in the same folder. These are compiled versions of the `.po` files create by Sphinx during the build process, and used to generate the translated version of the guide. They are intermediary files and are not meant to be edited directly or stored in the repository." +msgstr "" + +#: ../../TRANSLATING.md:114 +msgid "If you are working on a new translation, choose one of the `.po` files to start with. If you are working on an existing translation, you can start with the `.po` files that need the most work." +msgstr "" + +#: ../../TRANSLATING.md:116 +msgid "To see how much of each file has been translated, use the `sphinx-intl stat`. You will be able to see the number of translated, fuzzy, and untranslated strings in each `.po` file." +msgstr "" + +#: ../../TRANSLATING.md:118 +msgid "For example, to see the statistics for the Spanish translation, you would run:" +msgstr "" + +#: ../../TRANSLATING.md:132 +msgid "What do these categories mean:" +msgstr "" + +#: ../../TRANSLATING.md:134 +msgid "Translated strings are strings that have been translated into the target language." +msgstr "" + +#: ../../TRANSLATING.md:135 +msgid "Fuzzy strings are strings that have been translated but need to be reviewed because the original English string in the guide changed." +msgstr "" + +#: ../../TRANSLATING.md:136 +msgid "Untranslated strings are strings that have not been translated yet." +msgstr "" + +#: ../../TRANSLATING.md:139 +msgid "When Sphinx is building the guide in another language, it will look into the corresponding folder in `./locales/` for translated strings. If the translation is available, Sphinx will replace the English text with the equivalent text in the target language. If the translation is not available, Sphinx will use the original English strings." +msgstr "" + +#: ../../TRANSLATING.md:142 +msgid "Editing the Translation Files" +msgstr "" + +#: ../../TRANSLATING.md:144 +msgid "You can use any text editor to edit the `.po` file. But if you prefer, there are also tools like [Poedit](https://poedit.net/) that provide a graphic use interface." +msgstr "" + +#: ../../TRANSLATING.md:146 +msgid "Depending on your editor of choice, you may be able to install a plugin or extension that can provide syntax highlighting and other features for working with `.po` files. Like for example, the [gettext](https://marketplace.visualstudio.com/items?itemName=mrorz.language-gettext) extension for Visual Studio Code." +msgstr "" + +#: ../../TRANSLATING.md:148 +msgid "When you open a `.po` file, you will see a series of entries that look like this:" +msgstr "" + +#: ../../TRANSLATING.md:158 +msgid "The first line of an entry starts with `#:` and is a reference to the original source file and line number from which the text was extracted. This information is useful for finding the context of the text in the guide." +msgstr "" + +#: ../../TRANSLATING.md:160 +msgid "The `msgid` field contains the original English text that needs to be translated. The `msgstr` field is where you will enter the translated text. This field might contain text if someone else already translated the entry." +msgstr "" + +#: ../../TRANSLATING.md:170 +msgid "Sometimes the original English text may be too long for a single line, and it may be split into multiple lines. In this case, you can keep the same structure in the translated text. Notice that both the `msgid` and `msgstr` fields in the example below start with an empty string, indicating that the text continues in the next line." +msgstr "" + +#: ../../TRANSLATING.md:186 +msgid "The English text will sometimes contain Markdown formatting, such as bold or italic text. You should keep the formatting in the translated text, making sure to translate the text inside the formatting tags." +msgstr "" + +#: ../../TRANSLATING.md:188 +msgid "The English text may also contain links to other sections of the guide or external resources. You should keep the links in the translated text, making sure to update the link text when appropriate." +msgstr "" + +#: ../../TRANSLATING.md:196 +msgid "An entry may be marked as `fuzzy`, which means that the original English text has changed since the translation was made, and the translation may need to be revised. When this is the case you will see an additional line in the entry, starting with `#,`:" +msgstr "" + +#: ../../TRANSLATING.md:213 +msgid "You can review the translation and make any necessary changes, removing the `fuzzy` tag once you are satisfied with the translation." +msgstr "" + +#: ../../TRANSLATING.md:215 +msgid "You can also add comments to the translation file, by adding lines that start with a `#` character to the entry. This can be helpful to add context to the translation for other translators or reviewers to see, but this might be only necessary in special circumstances." +msgstr "" + +#: ../../TRANSLATING.md:218 +msgid "When working on a translation, you **should not** modify the original English text in the `msgid` field. If you see a typo or an error in the original text, please consider fixing it in the original source file (use the first line of the entry to locate it) and submit a separate pull request." +msgstr "" + +#: ../../TRANSLATING.md:221 +msgid "Building the Translated Documentation" +msgstr "" + +#: ../../TRANSLATING.md:223 +msgid "Once you finished translating or when you want to check the translation in context, you can build the guide locally on your computer, using the following command, replacing LANG by the proper language code (e.g., `es` for Spanish)" +msgstr "" + +#: ../../TRANSLATING.md:229 +msgid "This command will build all the translated versions of the guide defined in the `LANGUAGES` list in `noxfile.py`. These translations will be stored in the `_build/html`, in folders named after the language code (e.g., `es`, `fr`, etc.)." +msgstr "" + +#: ../../TRANSLATING.md:231 +msgid "To view the translated version of the guide in your browser, open the corresponding `index.html` file. For example, to view the Spanish translation, you would open `_build/html/es/index.html`." +msgstr "" + +#: ../../TRANSLATING.md:233 +msgid "You can also build a live version of the guide that updates automatically as you make changes to the translation files. To do this, use the `nox -s docs-live-lang` command. Note that in this case you need to specify which language you want to build. For example, if you are working on the Spanish translation, you would run:" +msgstr "" + +#: ../../TRANSLATING.md:239 +msgid "Note the `--` before the language code, it indicates that the following arguments should be passed into the nox session and not be interpreted directly by nox. If you forget the `--`, nox will look instead for a session named 'es' and raise an error that it does not exist." +msgstr "" + +#: ../../TRANSLATING.md:241 +msgid "This command will use `sphinx-autobuild` to launch a local web server where you can access the translated version of the guide. You can open the guide in your browser by navigating to `http://localhost:8000`." +msgstr "" + +#: ../../TRANSLATING.md:243 +msgid "This is a great way to see how the translated version of the guide looks as you make changes to the translation files." +msgstr "" + +#: ../../TRANSLATING.md:245 +msgid "Submitting a PR for Your Contribution" +msgstr "" + +#: ../../TRANSLATING.md:247 +msgid "Once you are finished translating and before you submit a pull request (PR) for your translation, you need to make sure that the translated version of the guide builds without any errors or warning and looks correctly in the browser." +msgstr "" + +#: ../../TRANSLATING.md:249 +msgid "You can follow these steps:" +msgstr "" + +#: ../../TRANSLATING.md:251 +msgid "Build the translations of the guide with same parameters that will be used during the release:" +msgstr "" + +#: ../../TRANSLATING.md:257 +msgid "Make sure there are no warnings or errors in the output. If there are, you will need to fix them before submitting the PR." +msgstr "" + +#: ../../TRANSLATING.md:258 +msgid "Make sure the translated version of the guide looks good in the browser by opening the `_build/html//index.html` file, where `` is the language you have been working on." +msgstr "" + +#: ../../TRANSLATING.md:260 +msgid "If everything looks good, you can submit a PR with your changes." +msgstr "" + +#: ../../TRANSLATING.md:263 +msgid "When you submit a PR for a translation, you should only include changes to one language. If you worked in multiple languages, please submit a separate PR for each language." +msgstr "" + +#: ../../TRANSLATING.md:266 +msgid "Translations PRs will be tagged with a label indicating the language to make them easier to identify and review. For example, contributions to the Spanish translation will be tagged with 'lang-es'." +msgstr "" + +#: ../../TRANSLATING.md:268 +msgid "TODO: This tagging could be automated with a GitHub Actions." +msgstr "" + +#: ../../TRANSLATING.md:270 +msgid "When you submit the PR, make sure to include a short description of the changes you made and any context that might be helpful for the reviewer (e.g., you translated new strings, you reviewed fuzzy entries, you fixed typos, etc.)" +msgstr "" + +#: ../../TRANSLATING.md:272 +msgid "The Review Process" +msgstr "" + +#: ../../TRANSLATING.md:274 +msgid "The review process for a translation contribution is similar to the review process for any other contribution to the guide." +msgstr "" + +#: ../../TRANSLATING.md:276 +msgid "TODO: This section needs more work, depending on the review workflow we decide to adopt. Other projects usually assign a coordinator/editor for each language, who is responsible for reviewing and merging translation contributions." +msgstr "" + +#: ../../TRANSLATING.md:278 +msgid "Each language has an assigned editor who is responsible for reviewing and merging translation contributions. The editor will review the changes to make sure they are accurate and consistent with the style and tone of the guide." +msgstr "" + +#: ../../TRANSLATING.md:280 +msgid "Sometimes the editor may ask for clarification or suggest changes to improve the translation. If this happens, you can make the requested changes and push them to the same branch where you submitted the original PR." +msgstr "" + +#: ../../TRANSLATING.md:282 +msgid "When the editor is satisfied with the translation, they will merge the PR. The translated version of the guide will be available on the pyOpenSci website once the language is released." +msgstr "" + +#: ../../TRANSLATING.md:284 +msgid "The Release Process" +msgstr "" + +#: ../../TRANSLATING.md:286 +msgid "If a language is ready to go live, the maintainers will add the language code to the `RELEASE_LANGUAGES` list in the `noxfile.py` configuration file." +msgstr "" + +#: ../../TRANSLATING.md:288 +msgid "When the guide is built for release in CI, Sphinx will also generate the translated versions of the guide for the languages in the `RELEASE_LANGUAGES` list." +msgstr "" + +#: ../../TRANSLATING.md:290 +msgid "Translations are released in the same way as the English version of the guide, and the translated versions will be available in folders named after the language code. For example, the Spanish translation will be available in [https://www.pyopensci.org/python-package-guide/es/](https://www.pyopensci.org/python-package-guide/es/)." +msgstr "" + +#: ../../TRANSLATING.md:292 +msgid "Frequently Asked Questions (FAQ)" +msgstr "" + +#: ../../TRANSLATING.md:294 +msgid "How do I know which strings need to be translated?" +msgstr "" + +#: ../../TRANSLATING.md:296 +msgid "When you run the `sphinx-intl stat` command, you will see a list of `.po` files with the number of translated, fuzzy, and untranslated strings. You can start by working on the files with the most untranslated strings." +msgstr "" + +#: ../../TRANSLATING.md:298 +msgid "What happens when a string has changed in the original English text?" +msgstr "" + +#: ../../TRANSLATING.md:300 +msgid "If a string has changed in the original English version, it will be marked as `fuzzy` in the translation file the next time it is updated (`update-language`, `update-all-languages`, or `update-all-release-languages`). Contributors working on the translation can then review the fuzzy entries and make the necessary changes to ensure it is accurate, before removing the `fuzzy` tag." +msgstr "" + +#: ../../TRANSLATING.md:302 +msgid "How do I handle links in the translated text?" +msgstr "" + +#: ../../TRANSLATING.md:304 +msgid "You should keep the links in the translated text, but make sure to update the link text if necessary. For example, if the original English text contains a link to `[What is a Python package?](/tutorials/intro)`, you should keep the link in the translated text but update the link text to `[¿Que es un paquete de Python?](/tutorials/intro)`." +msgstr "" + +#: ../../TRANSLATING.md:306 +msgid "How do I handle formatting in the translated text?" +msgstr "" + +#: ../../TRANSLATING.md:308 +msgid "You should keep the formatting in the translated text, but make sure to translate the text inside the formatting tags as well. For example, if the original English text is `**Test special cases:**`, you should keep the bold formatting in the translated text but update the text inside the formatting tags to `**Prueba casos especiales:**`." +msgstr "" + +#: ../../TRANSLATING.md:310 +msgid "How do I handle strings that are too long for a single line?" +msgstr "" + +#: ../../TRANSLATING.md:312 +msgid "If the original English text is too long for a single line, it may be split into multiple lines. Multiline strings in the `.po` file are indicated by an empty string in the `msgid` and `msgstr` fields, followed by the continuation of the text in the next line. For example:" +msgstr "" + +#: ../../TRANSLATING.md:325 +msgid "How do I translate images?" +msgstr "" + +#: ../../TRANSLATING.md:327 +msgid "You should not translate images in the guide. Producing translated versions of images is a complex process that requires additional tools and resources, and it is not typically done unless the translated images are created alongside the original images. More often, the text around the image is modified to include any necessary translations." +msgstr "" + +#: ../../TRANSLATING.md:329 +msgid "In some special cases, an image might be critical to the understanding of the content. In those cases, the translations will be handled by the maintainers and editors outside this workflow." +msgstr "" + +#: ../../TRANSLATING.md:331 +msgid "I am interested in translating the guide into a language that is not listed. How can I get started?" +msgstr "" + +#: ../../TRANSLATING.md:333 +msgid "If you want to start a new translation of the guide into a language that is not listed, you should [create an issue](https://github.com/pyOpenSci/python-package-guide/issues) in the repository to let the maintainers know that you intend to work on it. This will help avoid duplication of effort and ensure that the maintainers are ready to review your contribution when you are done." +msgstr "" + +#: ../../TRANSLATING.md:335 +msgid "How do I know when a translation is ready to be released?" +msgstr "" + +#: ../../TRANSLATING.md:337 +msgid "When a translation is ready to be included in the next release of the guide, the maintainers will add the language code to the `RELEASE_LANGUAGES` list in the `noxfile.py` configuration file. This will trigger the build of the translation during the release process, and the translated version of the guide will be available on the pyOpenSci website." +msgstr "" + +#: ../../TRANSLATING.md:339 +msgid "TODO: There are many approaches here, some projects release a translation as soon as some strings are translated, others wait until a certain percentage of the content is translated." +msgstr "" + +#: ../../TRANSLATING.md:341 +msgid "How can I get help with my translation?" +msgstr "" + +#: ../../TRANSLATING.md:343 +msgid "If you have any questions or need help with your translation, you can create an [issue](https://github.com/pyOpenSci/python-package-guide/issues) in the [Packaging Guide repository](https://github.com/pyOpenSci/python-package-guide)" +msgstr "" + +#: ../../TRANSLATING.md:345 +msgid "You can also ask in the PyOpenSci Discord server ([click here](https://discord.gg/NQtTTqtv) to join), you will find a general channel for questions related to our workflow, processes, and tools (translation-general) and channels for each of the languages we are working on (spanish-translation, japanese-translation, etc)." +msgstr "" diff --git a/locales/templates/LC_MESSAGES/continuous-integration.pot b/locales/templates/LC_MESSAGES/continuous-integration.pot new file mode 100644 index 00000000..f6a94e16 --- /dev/null +++ b/locales/templates/LC_MESSAGES/continuous-integration.pot @@ -0,0 +1,169 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2025, pyOpenSci +# This file is distributed under the same license as the pyOpenSci Python Package Guide package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: pyOpenSci Python Package Guide \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-04-30 18:44-0600\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../continuous-integration/ci.md:2 +msgid "Continuous Integration and Continuous Deployment (CI/CD) For Python Packages" +msgstr "" + +#: ../../continuous-integration/ci.md:4 +msgid "When you develop, work on, and contribute to software, there is more to consider than just writing code. Having tests and checks ensures that your code runs reliably and follows a consistent format is also important. You can use **Continuous Integration (CI)** and **Continuous Deployment (CD)** to run tests and checks on your code every time someone suggests a change online in a platform like GitHub or GitLab." +msgstr "" + +#: ../../continuous-integration/ci.md:11 +msgid "**Continuous Integration (CI):** Automates the process of running tests, code checks, and other workflows each time code is updated." +msgstr "" + +#: ../../continuous-integration/ci.md:13 +msgid "**Continuous Deployment (CD):** Extends CI by allowing you to automate publishing your package to PyPI, publishing your documentation, and more." +msgstr "" + +#: ../../continuous-integration/ci.md:15 +msgid "CI and CD streamline software development by automating repetitive tasks and ensuring code quality and consistency. Having CI setup also makes it easier for new contributors to contribute to your code base without setting up all your test suites and other local checks." +msgstr "" + +#: ../../continuous-integration/ci.md:20 +msgid "What is continuous integration?" +msgstr "" + +#: ../../continuous-integration/ci.md:22 +msgid "When you’re ready to publish your code online, you can set up Continuous Integration (CI). CI is a platform that allows you to specify and run jobs or workflows you define. These workflows include:" +msgstr "" + +#: ../../continuous-integration/ci.md:25 +msgid "Running your test suite" +msgstr "" + +#: ../../continuous-integration/ci.md:26 +msgid "Running code checkers / linters / spellcheck" +msgstr "" + +#: ../../continuous-integration/ci.md:27 +msgid "Building your documentation" +msgstr "" + +#: ../../continuous-integration/ci.md:29 +msgid "CI allows you to automate running workflows across a suite of environments, including:" +msgstr "" + +#: ../../continuous-integration/ci.md:31 +msgid "environments containing different Python versions and" +msgstr "" + +#: ../../continuous-integration/ci.md:32 +msgid "different operating systems (Mac, Linux, Windows)." +msgstr "" + +#: ../../continuous-integration/ci.md:34 +msgid "What is Continuous Deployment (CD)?" +msgstr "" + +#: ../../continuous-integration/ci.md:36 +msgid "Continuous deployment (CD) extends the CI process by automating the deployment of code changes to production or staging environments. In the case of your open source tool, CD can be used to:" +msgstr "" + +#: ../../continuous-integration/ci.md:38 +msgid "Automate publishing to PyPI" +msgstr "" + +#: ../../continuous-integration/ci.md:39 +msgid "Automate publishing your documentation to GitHub Pages or Read the Docs." +msgstr "" + +#: ../../continuous-integration/ci.md:41 +msgid "It is also used once your conda-forge recipe is set up to keep your package up to date on conda-forge." +msgstr "" + +#: ../../continuous-integration/ci.md:43 +msgid "Why use CI" +msgstr "" + +#: ../../continuous-integration/ci.md:45 +msgid "CI can be configured to run a workflow on every commit pushed to GitHub and every pull request opened. This ensures that any changes made to your package are tested across environments before merging into the main branch of your code." +msgstr "" + +#: ../../continuous-integration/ci.md:47 +msgid "These checks are particularly useful if someone new is contributing to your code. Every contributor's change will be tested when pushed to your code repository." +msgstr "" + +#: ../../continuous-integration/ci.md:49 +msgid "Together, CI and CD streamline the process of building, testing, and deploying code. They aim to improve software development and publication efficiency, quality, and reliability." +msgstr "" + +#: ../../continuous-integration/ci.md:52 +msgid "All pyOpenSci packages must use some form of continuous integration. Even if you are not planning to go through peer review, we strongly recommend that you use continuous integration, too!" +msgstr "" + +#: ../../continuous-integration/ci.md:55 +msgid "In the case of GitHub actions (which we will focus on here), CI workflows are running on online servers that support GitHub." +msgstr "" + +#: ../../continuous-integration/ci.md:57 +msgid "CI / CD platforms" +msgstr "" + +#: ../../continuous-integration/ci.md:59 +msgid "There are numerous platforms available for CI/CD. Here, we will focus on GitHub Actions (GHA), built into GitHub. GitHub is the most commonly used platform to store scientific open-source software." +msgstr "" + +#: ../../continuous-integration/ci.md:62 +msgid "If you use [GitLab](https://about.gitlab.com/) CI/CD, many of the principles described here will apply. However, the workflow files may look different." +msgstr "" + +#: ../../continuous-integration/ci.md:65 +msgid "If you aren't sure, use GitHub Actions" +msgstr "" + +#: ../../continuous-integration/ci.md:67 +msgid "While you are welcome to use the continuous integration platform of your choice, we recommend GitHub Actions because it is free-to-use and integrated tightly into the GitHub user interface. There is also an entire store of GitHub action templates that you can easily use and adapt to your own needs." +msgstr "" + +#: ../../continuous-integration/ci.md:72 +msgid "Other platforms that you may run into" +msgstr "" + +#: ../../continuous-integration/ci.md:75 +msgid "[Appveyor:](https://www.appveyor.com/): Supports running tests on Windows operating systems and predated the release of GitHub Actions. Today, AppVeyor supports operating systems beyond Windows." +msgstr "" + +#: ../../continuous-integration/ci.md:76 +msgid "[Travis CI:](https://www.travis-ci.com/) had been a common CI platform choice in our ecosystem. Usage dropped after Travis CI ended free support for open-source projects." +msgstr "" + +#: ../../continuous-integration/ci.md:77 +msgid "[CircleCI:](https://circleci.com/) CircleCI can be useful for automated builds of websites and documentation since it offers a preview of the PR changes." +msgstr "" + +#: ../../continuous-integration/ci.md:80 +msgid "Embrace automation" +msgstr "" + +#: ../../continuous-integration/ci.md:82 +msgid "By embracing CI/CD, you can ensure that your code runs as you expect it to across the diverse landscapes of user environments. Further, you can automate certain checks (and, in some cases, code fixes), including linting and code style. You can even automate spell-checking your documentation and docstrings!" +msgstr "" + +#: ../../continuous-integration/index.md:5 +msgid "What is CI?" +msgstr "" + +#: ../../continuous-integration/index.md:5 +msgid "Continuous Integration" +msgstr "" + +#: ../../continuous-integration/index.md:2 +msgid "Continuous Integration (CI) and Continuous Deployment (CD) for your Python package" +msgstr "" diff --git a/locales/templates/LC_MESSAGES/documentation.pot b/locales/templates/LC_MESSAGES/documentation.pot new file mode 100644 index 00000000..dd7584bf --- /dev/null +++ b/locales/templates/LC_MESSAGES/documentation.pot @@ -0,0 +1,1892 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2025, pyOpenSci +# This file is distributed under the same license as the pyOpenSci Python Package Guide package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: pyOpenSci Python Package Guide \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-04-30 18:44-0600\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../documentation/hosting-tools/intro.md:1 +msgid "Tools to Build and Host your Documentation" +msgstr "" + +#: ../../documentation/hosting-tools/intro.md:3 +msgid "The most common tool for building documentation in the Python ecosystem currently is Sphinx. However, some maintainers are using tools like [mkdocs](https://www.mkdocs.org/) for documentation. It is up to you to use the platform that you prefer for your documentation!" +msgstr "" + +#: ../../documentation/hosting-tools/intro.md:8 +msgid "In this section, we introduce Sphinx as a common tool to build documentation. We talk about various syntax options that you can use when writing Sphinx documentation including mySt and rST." +msgstr "" + +#: ../../documentation/hosting-tools/intro.md:12 +msgid "We also talk about ways to publish your documentation online and Sphinx tools that might help you optimize your documentation website." +msgstr "" + +#: ../../documentation/hosting-tools/myst-markdown-rst-doc-syntax.md:1 +msgid "Documentation syntax: markdown vs. myST vs. rst syntax to create your docs" +msgstr "" + +#: ../../documentation/hosting-tools/myst-markdown-rst-doc-syntax.md:3 +msgid "There are three commonly used syntaxes for creating Python documentation:" +msgstr "" + +#: ../../documentation/hosting-tools/myst-markdown-rst-doc-syntax.md:4 +msgid "[markdown](https://www.markdownguide.org/): Markdown is an easy-to-learn text syntax. It is the default syntax used in Jupyter Notebooks. There are tools that you can add to a Sphinx website that allow it to render markdown as html. However, using markdown to write documentation has limitations. For instance if you want to add references, colored call out blocks and other custom elements to your documentation, you will need to use either **myST** or **rST**." +msgstr "" + +#: ../../documentation/hosting-tools/myst-markdown-rst-doc-syntax.md:8 +msgid "[rST (ReStructured Text):](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html). **rST** is the native syntax that sphinx supports. rST was the default syntax used for documentation for many years. However, in recent years myST has risen to the top as a favorite for documentation given the flexibility that it allows." +msgstr "" + +#: ../../documentation/hosting-tools/myst-markdown-rst-doc-syntax.md:9 +msgid "[myST:](https://myst-parser.readthedocs.io/en/latest/intro.html) myST is a combination of `markdown` and `rST` syntax. It is a nice option if you are comfortable writing markdown. `myst` is preferred by many because it offers both the rich functionality of rST combined with a simple-to-write markdown syntax." +msgstr "" + +#: ../../documentation/hosting-tools/myst-markdown-rst-doc-syntax.md:12 +msgid "While you can chose to use any of the syntaxes listed above, we suggest using `myST` because:" +msgstr "" + +#: ../../documentation/hosting-tools/myst-markdown-rst-doc-syntax.md:15 +msgid "It is a simpler syntax and thus easier to learn;" +msgstr "" + +#: ../../documentation/hosting-tools/myst-markdown-rst-doc-syntax.md:16 +msgid "The above simplicity will make it easier for more people to contribute to your documentation." +msgstr "" + +#: ../../documentation/hosting-tools/myst-markdown-rst-doc-syntax.md:17 +msgid "Most of your core Python package text files, such as your README.md file, are already in `.md` format" +msgstr "" + +#: ../../documentation/hosting-tools/myst-markdown-rst-doc-syntax.md:18 +msgid "`GitHub` and `Jupyter Notebooks` support markdown thus it's more widely used in the scientific ecosystem." +msgstr "" + +#: ../../documentation/hosting-tools/myst-markdown-rst-doc-syntax.md:22 +msgid "If you are on the fence about myST vs rst, you might find that **myST** is easier for more people to contribute to." +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:1 +msgid "How to publish your Python package documentation online" +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:3 +msgid "We suggest that you setup a hosting service for your Python package documentation. Two free and commonly used ways to quickly create a documentation website hosting environment are below." +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:7 +msgid "You can host your documentation yourself using [GitHub Pages](https://pages.github.com/) or another online hosting service." +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:8 +msgid "You can host your documentation using [Read the Docs](https://readthedocs.org/)." +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:10 +msgid "What is Read the Docs ?" +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:11 +msgid "[Read the Docs](https://readthedocs.org/) is a documentation hosting service that supports publishing your project's documentation." +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:13 +msgid "Read the Docs is a fully featured, free, documentation hosting service. Some of its many features include:" +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:16 +msgid "Is free to host your documentation (but there are also paid tiers if you wish to customize hosting)" +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:17 +msgid "Automates building your documentation" +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:18 +msgid "Allows you to turn on integration with pull requests where you can view documentation build progress (success vs failure)." +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:19 +msgid "Supports versioning of your documentation which allows users to refer to older tagged versions of the docs if they are using older versions of your package." +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:20 +msgid "Supports downloading of documentation in PDF and other formats." +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:21 +msgid "You can customize the documentation build using a **.readthedocs.yaml** file in your GitHub repository." +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:24 +msgid "What is GitHub Pages?" +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:25 +msgid "[GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages) is a free web hosting service offered by GitHub. Using GitHub pages, you can build your documentation locally or using a Continuous Integration setup, and then push to a branch in your GitHub repository that is setup to run the GitHub Pages web build." +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:33 +msgid "Read the Docs vs GitHub Pages" +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:35 +msgid "GitHub pages is a great option for your documentation deployment. However, you will need to do a bit more work to build and deploy your documentation if you use GitHub pages." +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:39 +msgid "Read the Docs can be setup in your Read the Docs user account. The service automates the entire process of building and deploying your documentation." +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:42 +msgid "If you don't want to maintain a documentation website for your Python package, we suggest using the Read the Docs website." +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:1 +msgid "Using Sphinx to Build Python Package Documentation" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:17 +msgid "On this page we discuss using [Sphinx](https://www.sphinx-doc.org/) to build your user-facing package documentation. While Sphinx is currently the most commonly-used tool in the scientific Python ecosystem, you are welcome to explore other tools to build documentation such as [mkdocs](https://www.mkdocs.org/) which is gaining popularity in the Python packaging ecosystem." +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:25 +msgid "Examples of documentation websites that we love:" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:27 +msgid "[GeoPandas](https://geopandas.org/en/stable/)" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:28 +msgid "[View rst to create landing page](https://raw.githubusercontent.com/geopandas/geopandas/main/doc/source/index.rst)" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:29 +msgid "[verde](https://www.fatiando.org/verde/latest/)" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:30 +msgid "[View verde landing page code - rst file.](https://github.com/fatiando/verde/blob/main/doc/index.rst)" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:31 +msgid "[Here is our documentation if you want to see a myST example of a landing page.](https://github.com/pyOpenSci/python-package-guide/blob/main/index.md)" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:34 +msgid "Sphinx - a static site generator" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:36 +msgid "Sphinx is a [static-site generator](https://www.cloudflare.com/learning/performance/static-site-generator/). A static site generator is a tool that creates html for a website based upon a set of templates. The html files are then served \"Statically\" which means that there is no generation or modification of the files on the fly." +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:39 +msgid "Sphinx is written using Python." +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:41 +msgid "Sphinx sites can be customized using extensions and themes" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:43 +msgid "The functionality of Sphinx can be extended using extensions and themes. A few examples include:" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:46 +msgid "You can apply documentation themes for quick generation of beautiful documentation." +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:47 +msgid "You can [automatically create documentation for your package's functions and classes (the package's API) from docstrings in your code using the autodoc extension](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html)" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:48 +msgid "You can [run and test code examples in your docstrings using the doctest extension](https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html)" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:49 +msgid "While Sphinx natively supports the `rST` syntax, you can add custom syntax parsers to support easier-to-write syntax using tools such as [the MyST parser](https://myst-parser.readthedocs.io/)." +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:51 +msgid "Commonly used Sphinx themes" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:53 +msgid "You are free to use whatever Sphinx theme that you prefer. However, the most common Sphinx themes used in the Python scientific community include:" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:57 +msgid "[pydata-sphinx-theme](https://pydata-sphinx-theme.readthedocs.io/)" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:58 +msgid "[sphinx-book-theme](https://sphinx-book-theme.readthedocs.io/)" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:59 +msgid "[furo](https://pradyunsg.me/furo/quickstart/)" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:63 +msgid "This book is created using Sphinx and the `furo` theme." +msgstr "" + +#: ../../documentation/hosting-tools/website-hosting-optimizing-your-docs.md:1 +msgid "Optimizing your documentation so search engines (and other users) find it" +msgstr "" + +#: ../../documentation/hosting-tools/website-hosting-optimizing-your-docs.md:3 +msgid "If you are interested in more people finding your package, you may want to add some core Sphinx extensions (and theme settings) that will help search engines such as Google find your documentation." +msgstr "" + +#: ../../documentation/hosting-tools/website-hosting-optimizing-your-docs.md:7 +msgid "Google Analytics" +msgstr "" + +#: ../../documentation/hosting-tools/website-hosting-optimizing-your-docs.md:11 +msgid "Google analytics [is not compliant with the European General Data Protection Regulation (GDPR)](https://matomo.org/blog/2022/05/google-analytics-4-gdpr/). While there are many components to this regulation, one of the core elements is that you have to let users know on your site that you are collecting data and they have to consent. While it is possible to add infrastructure around Google Analytics to make it close to following GDPR regulations, the community is slowly shifting away from Google using open tools such as [Plausible](https://plausible.io/), [Cloudflare Web Analytics](https://www.cloudflare.com/web-analytics/) and [Matomo](https://matomo.org) for web analytics." +msgstr "" + +#: ../../documentation/hosting-tools/website-hosting-optimizing-your-docs.md:13 +msgid "pyOpenSci is currently looking into free options for open source developers." +msgstr "" + +#: ../../documentation/hosting-tools/website-hosting-optimizing-your-docs.md:16 +msgid "Some of the [sphinx themes such as the `pydata-sphinx-theme` and sphinx-book-theme have built in support for Google Analytics](https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/analytics.html#google-analytics). However, if the theme that you chose does not offer Google Analytics support, you can use the [`sphinxcontrib-gtagjs` extension](https://github.com/attakei/sphinxcontrib-gtagjs). This extension will add a Google Analytics site tag to each page of your documentation." +msgstr "" + +#: ../../documentation/hosting-tools/website-hosting-optimizing-your-docs.md:22 +msgid "[sphinx-sitemap](https://sphinx-sitemap.readthedocs.io/en/latest/index.html) for search engine optimization" +msgstr "" + +#: ../../documentation/hosting-tools/website-hosting-optimizing-your-docs.md:24 +msgid "While we are trying to move away from Google Analytics do to compliance and privacy issues, search engine optimization is still important. Google is the most popular search engine. And if your documentation is search optimized, users are more likely to find your package!" +msgstr "" + +#: ../../documentation/hosting-tools/website-hosting-optimizing-your-docs.md:30 +msgid "If you are interested in optimizing your documentation for search engines such as Google, you want a **sitemap.xml** file. You can submit this sitemap to Google and it will index your entire site. This over time can make the content on your site more visible to others when they search." +msgstr "" + +#: ../../documentation/hosting-tools/website-hosting-optimizing-your-docs.md:36 +msgid "This extension is lightweight." +msgstr "" + +#: ../../documentation/hosting-tools/website-hosting-optimizing-your-docs.md:38 +msgid "It [requires that you to add it to your Sphinx `conf.py` extension list and site your documentation base url](https://sphinx-sitemap.readthedocs.io/en/latest/getting-started.html)." +msgstr "" + +#: ../../documentation/hosting-tools/website-hosting-optimizing-your-docs.md:40 +msgid "[sphinxext.opengraph](https://github.com/wpilibsuite/sphinxext-opengraph)" +msgstr "" + +#: ../../documentation/hosting-tools/website-hosting-optimizing-your-docs.md:42 +msgid "OpenGraph is an extension that allows you to add metadata to your documentation content pages. [The OpenGraph protocol allows other websites to provide a useful preview of the content on your page when shared](https://www.freecodecamp.org/news/what-is-open-graph-and-how-can-i-use-it-for-my-website/#heading-what-is-open-graph). This is important for when the pages in your documentation are shared on social media sites like Twitter and Mastodon and even for shares on tools like Slack and Discourse." +msgstr "" + +#: ../../documentation/index.md:3 +msgid "Documentation Overview" +msgstr "" + +#: ../../documentation/index.md:3 +#: ../../documentation/index.md:10 +#: ../../documentation/index.md:21 +#: ../../documentation/index.md:42 +msgid "Intro" +msgstr "" + +#: ../../documentation/index.md:10 +msgid "Create Your Docs" +msgstr "" + +#: ../../documentation/index.md:10 +msgid "Document Your Code (API)" +msgstr "" + +#: ../../documentation/index.md:10 +msgid "Create Package Tutorials" +msgstr "" + +#: ../../documentation/index.md:10 +msgid "Write User Documentation" +msgstr "" + +#: ../../documentation/index.md:21 +msgid "Contributing File" +msgstr "" + +#: ../../documentation/index.md:21 +msgid "Development Guide" +msgstr "" + +#: ../../documentation/index.md:21 +msgid "Changelog File" +msgstr "" + +#: ../../documentation/index.md:21 +msgid "Docs for Contributors & Maintainers" +msgstr "" + +#: ../../documentation/index.md:32 +msgid "README file" +msgstr "" + +#: ../../documentation/index.md:32 +msgid "Code of Conduct File" +msgstr "" + +#: ../../documentation/index.md:32 +msgid "LICENSE files" +msgstr "" + +#: ../../documentation/index.md:32 +msgid "Community Docs" +msgstr "" + +#: ../../documentation/index.md:42 +msgid "Sphinx for Docs" +msgstr "" + +#: ../../documentation/index.md:42 +msgid "myST vs Markdown vs rst" +msgstr "" + +#: ../../documentation/index.md:42 +msgid "Publish Your Docs" +msgstr "" + +#: ../../documentation/index.md:42 +msgid "Website Hosting and Optimization" +msgstr "" + +#: ../../documentation/index.md:42 +msgid "Publication tools for your docs" +msgstr "" + +#: ../../documentation/index.md:1 +msgid "Documentation for your Open Source Python Package" +msgstr "" + +#: ../../documentation/index.md:55 +msgid "Please note that the tools discussed here are those that we see commonly used in the community. As tools evolve we will update this guide. If you are submitting a package for pyOpenSci peer review and use other tools that are not listed in our guide to build your package you can still submit for review! The tools listed here are suggestions, not requirements. Our requirements are focused on the documentation content of your package." +msgstr "" + +#: ../../documentation/index.md:65 +msgid "Documentation is critical for your Python package's success" +msgstr "" + +#: ../../documentation/index.md:67 +msgid "Documentation is as important to the success of your Python open source package as the code itself." +msgstr "" + +#: ../../documentation/index.md:70 +msgid "Quality code is of course valuable as its how your package gets the tasks done. However, if users don't understand how to use your package in their workflows, then they won't use it." +msgstr "" + +#: ../../documentation/index.md:73 +msgid "Further, explicitly documenting how to contribute is important if you wish to build a base of contributors to your package." +msgstr "" + +#: ../../documentation/index.md:76 +msgid "Two types of Python package users" +msgstr "" + +#: ../../documentation/index.md:78 +msgid "The documentation that you write for your package should target two types of users:" +msgstr "" + +#: ../../documentation/index.md:81 +msgid "1. Basic Tool Users" +msgstr "" + +#: ../../documentation/index.md:83 +msgid "Basic tool users are the people who will use your package code in their Python workflows. They might be new(er) to Python and/or data science. Or expert programmers. But they might not have a background in software development. These users need to know:" +msgstr "" + +#: ../../documentation/index.md:88 +msgid "How to install your package" +msgstr "" + +#: ../../documentation/index.md:89 +msgid "How to install dependencies that your package requires" +msgstr "" + +#: ../../documentation/index.md:90 +msgid "How to get started using the code base" +msgstr "" + +#: ../../documentation/index.md:91 +msgid "Information on how to cite your code / give you credit if they are using it in a research application." +msgstr "" + +#: ../../documentation/index.md:93 +msgid "Information on the license that your code uses so they know how they can or can't use the code in an operational setting." +msgstr "" + +#: ../../documentation/index.md:96 +msgid "2. Potential tool contributors" +msgstr "" + +#: ../../documentation/index.md:98 +msgid "The other subset of users are more experienced and/or more engaged with your package. As such they are potential contributors. These users:" +msgstr "" + +#: ../../documentation/index.md:102 +msgid "might have a software development background," +msgstr "" + +#: ../../documentation/index.md:103 +msgid "might also be able to contribute bug fixes to your package or updates to your documentation" +msgstr "" + +#: ../../documentation/index.md:104 +msgid "might also just be users who will find spelling errors in your documentation, or bugs in your tutorials." +msgstr "" + +#: ../../documentation/index.md:106 +msgid "These users need all of the things that a basic user needs. But, they also need to understand how you'd like for them to contribute to your package. These potential contributors need:" +msgstr "" + +#: ../../documentation/index.md:110 +msgid "A development guide to help them understand the infrastructure used in your package repository." +msgstr "" + +#: ../../documentation/index.md:111 +msgid "Contributing guidelines that clarify the types of contributions that you welcome and how you'd prefer those contributions to be submitted." +msgstr "" + +#: ../../documentation/index.md:114 +msgid "It's important to remember that the definition of what a contribution is can be broad. A contribution could be something as simple as a bug report. Or fixing a spelling issue in your documentation. Or it could be a code fix that includes a new test that covers an edge-case that they discovered." +msgstr "" + +#: ../../documentation/index.md:120 +msgid "Documentation elements that pyOpenSci looks for reviewing a Python package" +msgstr "" + +#: ../../documentation/index.md:122 +msgid "In the pyOpenSci open peer review, we look for a documentation structure that supports both your tool users and potential contributors. The files and elements that we look for specifically can be found in our peer review check list (see link below)." +msgstr "" + +#: ../../documentation/index.md:127 +msgid "In this guide, we discuss each required element, and also discuss other elements that you should consider in your package's documentation in more detail." +msgstr "" + +#: ../../documentation/index.md:131 +msgid "View pyOpenSci peer review check list" +msgstr "" + +#: ../../documentation/index.md:138 +msgid "Image showing the files in the the MovingPandas GitHub repository. Files in the image include code of conduct.md contributing.md license.txt and readme.md." +msgstr "" + +#: ../../documentation/index.md:144 +msgid "An example from the MovingPandas GitHub repository with all of the major files in it including CONTRIBUTING.md, README.md, CODE_OF_CONDUCT.md and a LICENSE.txt file. *(screen shot taken Nov 23 2022)*" +msgstr "" + +#: ../../documentation/index.md:147 +msgid "What's next in this Python package documentation section?" +msgstr "" + +#: ../../documentation/index.md:149 +msgid "In this section of the pyOpenSci package guide, we will walk you through best practices for setting up documentation for your Python package. We will also suggest tools that you can use to build your user-facing documentation website." +msgstr "" + +#: ../../documentation/index.md:154 +msgid "Todo" +msgstr "" + +#: ../../documentation/index.md:156 +msgid "Python version support You should always be explicit about which versions of Python your package supports. Keeping compatibility with old Python versions can be difficult as functionality changes. A good rule of thumb is that the package should support, at least, the latest three Python versions (e.g., 3.8, 3.7, 3.6)." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:1 +msgid "CHANGELOG.md Guide" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:3 +msgid "Introduction" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:5 +msgid "The `CHANGELOG.md` document serves as a valuable resource for developers and users alike to track the evolution of a project over time. Understanding the structure and purpose of a changelog helps users and contributors stay informed about new features, bug fixes, and other changes introduced in each release." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:7 +msgid "What is CHANGELOG.md?" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:9 +msgid "The primary purpose of `CHANGELOG.md` is to provide a record of notable changes made to the project with each new release. This document helps users understand what has been added, fixed, modified, or removed with each version of the software." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:11 +msgid "[Keep a CHAGELOG.md](https://keepachangelog.com/en/1.1.0/) is a great, simple resource for understanding what a changelog is and how to create a good changelog. It also includes examples of things to avoid." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:13 +msgid "Versioning your Python package and semantic versioning" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:16 +msgid "An important component of a package that serves as the backbone behind the changelog file is a good versioning scheme. Semantic Versioning is widely used across Python packages." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:17 +msgid "[Creating New Versions of Your Python Package](../../package-structure-code/python-package-versions.md)" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:18 +msgid "[Semantic Versioning](https://semver.org)" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:21 +msgid "Why is it important?" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:23 +msgid "A well-maintained changelog is essential for transparent communication with users and developers. It serves as a centralized hub for documenting changes and highlights the progress made in each release. By keeping the changelog up-to-date, project maintainers can build trust with their user base and demonstrate their commitment to improving the software." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:25 +msgid "What does it include?" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:27 +msgid "The contents of a changelog.md file typically follow a structured format, detailing the changes introduced in each release. While the exact format may vary depending on the project's conventions, some common elements found in changelogs for Python packages include:" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:29 +msgid "**Versioning**: Clear identification of each release version using semantic versioning or another versioning scheme adopted by the project." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:31 +msgid "**Release Date**: The date when each version was released to the public, providing context for the timeline of changes." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:33 +msgid "**Change Categories**: Organizing changes into categories such as \"Added,\" \"Changed,\" \"Fixed,\" and \"Removed\" to facilitate navigation and understanding." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:35 +msgid "**Description of Changes**: A concise description of the changes made in each category, including new features, enhancements, bug fixes, and deprecated functionality." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:37 +msgid "**Links to Issues or Pull Requests**: References to relevant issue tracker items or pull requests associated with each change, enabling users to access more detailed information if needed." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:39 +msgid "**Upgrade Instructions**: Guidance for users on how to upgrade to the latest version, including any breaking changes or migration steps they need to be aware of." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:41 +msgid "**Contributor Recognition**: Acknowledgment of contributors who made significant contributions to the release, fostering a sense of community and appreciation for their efforts." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:43 +msgid "How do maintainers use it?" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:45 +msgid "Often you will see a changelog that documents a few things:" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:47 +msgid "Unreleased Section" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:49 +msgid "Unreleased commits are at the top of the changelog, commonly in an `Unreleased` section. This is where you can add new fixes, updates and features that have been added to the package since the last release." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:51 +msgid "This section might look something like this:" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:59 +msgid "Release Sections" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:61 +msgid "When you are ready to make a new release, you can move the elements into a section that is specific to that new release number." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:63 +msgid "This specific release section will sit below the unreleased section and can include any updates, additions, deprecations and contributors." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:65 +msgid "The unreleased section then always lives at the top of the file and new features continue to be added there. At the same time, after releasing a version like v1.0 all of its features remain in that specific section." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:83 +msgid "What does it look like?" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:85 +msgid "This example comes from [Devicely](https://github.com/hpi-dhc/devicely/blob/main/CHANGELOG.md), a pyOpenSci accepted package." +msgstr "" + +#: ../../documentation/repository-files/code-of-conduct-file.md:3 +msgid "The CODE_OF_CONDUCT file - Python Packaging" +msgstr "" + +#: ../../documentation/repository-files/code-of-conduct-file.md:5 +msgid "Example CODE_OF_CONDUCT files" +msgstr "" + +#: ../../documentation/repository-files/code-of-conduct-file.md:8 +msgid "[SciPy Code of Conduct file - notice they included theirs in their documentation](https://docs.scipy.org/doc/scipy/dev/conduct/code_of_conduct.html)" +msgstr "" + +#: ../../documentation/repository-files/code-of-conduct-file.md:9 +msgid "[fatiando CODE_OF_CONDUCT.md file](https://github.com/fatiando/community/blob/main/CODE_OF_CONDUCT.md)" +msgstr "" + +#: ../../documentation/repository-files/code-of-conduct-file.md:12 +msgid "Your package should have a `CODE_OF_CONDUCT.md` file located the root of the repository. Once you have people using your package, you can consider the package itself as having a community around it. Some of this community uses your tool. These users may have questions or encounter challenges using your package." +msgstr "" + +#: ../../documentation/repository-files/code-of-conduct-file.md:18 +msgid "Others in the community might want to contribute to your tool. They might fix bugs, update documentation and engage with the maintainer team." +msgstr "" + +#: ../../documentation/repository-files/code-of-conduct-file.md:22 +msgid "Why you need a CODE_OF_CONDUCT" +msgstr "" + +#: ../../documentation/repository-files/code-of-conduct-file.md:24 +msgid "In order to keep this community healthy and to protect yourself, your maintainer team and your users from unhealthy behavior, it is important to have a [`CODE_OF_CONDUCT`](https://opensource.guide/code-of-conduct/)." +msgstr "" + +#: ../../documentation/repository-files/code-of-conduct-file.md:28 +msgid "The `CODE_OF_CONDUCT` is important as it establishes what you expect in terms of how users and contributors interact with maintainers and each other. It also establishes rules and expectations which can then be enforced if need be to protect others from harmful and/or negative behaviors." +msgstr "" + +#: ../../documentation/repository-files/code-of-conduct-file.md:34 +msgid "If you are not comfortable with creating your own `CODE_OF_CONDUCT` text, we encourage you to adopt the `CODE_OF_CONDUCT` language used in the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). [Many other communities](https://www.contributor-covenant.org/adopters/) have adopted this `CODE_OF_CONDUCT` as their own. See the [Fatiando a Terra Geoscience Python community's example here.](https://github.com/fatiando/community/blob/main/CODE_OF_CONDUCT.md)" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:2 +msgid "Your Python Package CONTRIBUTING File" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:4 +msgid "The **CONTRIBUTING.md** is the landing page guide for your project's contributors. It outlines how contributors can get involved, the contribution types that you welcome, and how contributors should interact or engage with you and your maintainer team. The contributor guide should also link to get-started resources that overview how to set up development environments, what type of workflow you expect on GitHub/GitLab, and anything else that contributors might need to get started." +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:6 +msgid "This file benefits maintainers and contributors. For contributors, it provides a roadmap that helps them get started and makes their first contribution easier. For maintainers, it answers commonly asked questions and reduces the burden of explaining your process to every person who wants to contribute. This document creates a more collaborative and efficient development process for everyone." +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:8 +msgid "CONTRIBUTING files lower barriers to entry" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:10 +msgid "The contributing file lowers barriers to entry for new and seasoned contributors as it provides a roadmap." +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:12 +msgid "**For Contributors**: It provides clear instructions on contributing, from reporting issues to submitting pull requests." +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:13 +msgid "**For Maintainers**: It streamlines contributions by setting expectations and standardizing processes, reducing the time spent clarifying common questions or handling incomplete issues or pull requests." +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:15 +msgid "Including a well-written CONTRIBUTING.md file in your project is one way of making it more welcoming and open to new and seasoned contributors. It also helps create a smoother workflow for everyone involved." +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:17 +msgid "Make it welcoming" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:19 +msgid "Make the guide welcoming. Use accessible language to encourage participation from contributors of all experience levels. For example:" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:21 +msgid "Avoid technical jargon or explain terms when necessary (for example, \"fork the repository\")." +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:22 +msgid "Include a friendly introduction, such as \"Thank you for your interest in contributing! We're excited to collaborate with you.\"" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:23 +msgid "Highlight that all contributions, no matter how small, are valued." +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:25 +msgid "What a CONTRIBUTING.md file should contain" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:27 +msgid "Example contributing files" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:30 +msgid "[PyGMT contributing file](https://github.com/GenericMappingTools/pygmt/blob/main/CONTRIBUTING.md)" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:31 +msgid "[Verde's contributing file](https://github.com/fatiando/verde/blob/main/CONTRIBUTING.md)" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:34 +msgid "Your Python package should include a file called **CONTRIBUTING.md** located in the root of your repository next to [your **README.md** file](readme-file)." +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:37 +msgid "The CONTRIBUTING.md file should include information about:" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:39 +msgid "The types of contributions that you welcome" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:41 +msgid "Example: We welcome contributions of all kinds. If you want to address an existing issue, check out our issues in this repository and comment on the one that you'd like to help with. Otherwise, you can open a new issue..." +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:43 +msgid "How you'd like contributions to happen. Clearly outline your contribution process. For example:" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:44 +msgid "Should contributors address open issues" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:45 +msgid "Are new issues welcome?" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:46 +msgid "Should contributors open a pull request (PR) directly or discuss changes first?" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:48 +msgid "Include instructions for the fork and pull request workflow and link to resources or guides explaining these steps (if available)." +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:49 +msgid "Guidelines that you have in place for users submitting issues, pull requests, or asking questions." +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:51 +msgid "If you have a [development guide](development-guide), link to it. This guide should provide clear instructions on how to set up your development environment locally. It also should overview CI tools that you have that could simplify the contribution process (for example, pre-[commit.ci bot](https://www.pyopensci.org/python-package-guide/package-structure-code/code-style-linting-format.html#pre-commit-ci), and so on), [linters, code formatters](https://www.pyopensci.org/python-package-guide/package-structure-code/code-style-linting-format.html#code-linting-formatting-and-styling-tools), and so on." +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:53 +msgid "This guide should also include information for someone interested in asking questions. Some projects accept questions as GitHub or GitLab issues. Others use GitHub discussions, Discourse, or even a Discord server." +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:56 +msgid "The contributing file should also include:" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:58 +msgid "A link to your [code of conduct](coc-file)" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:59 +msgid "A link to your project's [LICENSE](license-file)" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:60 +msgid "A link to a [development guide](development-guide) if you have one" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:62 +msgid "Summary" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:64 +msgid "A well-crafted CONTRIBUTING.md file is welcome mat for your project! By providing clear instructions, helpful resources, and a welcoming tone, you make it easier for contributors to get involved and build a stronger, more collaborative community around your project." +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:2 +msgid "What the development guide for your Python package should contain" +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:4 +msgid "Ideally, your package should also have a development guide. This file may live in your package documentation and should be linked to from your CONTRIBUTING.md file (discussed above). A development guide should clearly show technically proficient users how to:" +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:8 +msgid "Set up a development environment locally to work on your package" +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:9 +msgid "Run the test suite" +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:10 +msgid "Build documentation locally" +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:12 +msgid "The development guide should also have guidelines for:" +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:14 +msgid "code standards including docstring style, code format and any specific code approaches that the package follows." +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:16 +msgid "It's also helpful to specify the types of tests you request if a contributor submits a new feature or a change to an existing feature that will not be covered by your existing test suite." +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:18 +msgid "If you have time to document it, it's also helpful to document your maintainer workflow and release processes." +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:20 +msgid "Why a development guide is important" +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:22 +msgid "It's valuable to have a development guide, in the case that you wish to:" +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:25 +msgid "Onboard new maintainers." +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:26 +msgid "Allow technically inclined contributors to make thoughtful and useful code based pull requests to your repository." +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:28 +msgid "It also is important to pyOpenSci that the maintenance workflow is documented in the case that we need to help you onboard new maintainers in the future." +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:33 +msgid "A well thought out continuous integration setup in your repository can allow users to skip building the package locally (especially if they are just updating text)." +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:38 +msgid "A development guide, while strongly recommended, is not a file that pyOpenSci requires a package to have in order to be eligible for review. Some maintainers may also opt to include the development information in their contributing guide." +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:44 +msgid "[The Mozilla Science Lab website has a nice outline of things to consider when creating a contributing guide](https://mozillascience.github.io/working-open-workshop/contributing/)" +msgstr "" + +#: ../../documentation/repository-files/intro.md:1 +msgid "Documentation Files That Should be in your Python Package Repository" +msgstr "" + +#: ../../documentation/repository-files/intro.md:3 +msgid "In this section of the Python packaging guide, we review all of the files that you should have in your Python package repository. Your Python package should, at a minimum have the following files:" +msgstr "" + +#: ../../documentation/repository-files/intro.md:7 +msgid "The files mentions above (README, Code of Conduct, license file, etc) are used as a measure of package community health on many online platforms. Below, you can see an example how GitHub evaluates community health. This community health link is available for all GitHub repositories." +msgstr "" + +#: ../../documentation/repository-files/intro.md:13 +msgid "Image showing that the MovingPandas GitHub repository community health page with green checks next to each file including a description, README, code of conduct, contributing, license and issue templates. Note that Security policy has a yellow circle next to it as that is missing from the repo." +msgstr "" + +#: ../../documentation/repository-files/intro.md:19 +msgid "GitHub community health looks for a readme file among other elements when it evaluates the community level health of your repository. This example is from the [MovingPandas GitHub repo](https://github.com/anitagraser/movingpandas/community) *(screen shot taken Nov 23 2022)*" +msgstr "" + +#: ../../documentation/repository-files/intro.md:22 +msgid "[Snyk](https://snyk.io/advisor/python) is another well-known company that keeps tabs on package health. Below you can see a similar evaluation of files in the GitHub repo as a measure of community health." +msgstr "" + +#: ../../documentation/repository-files/intro.md:26 +msgid "Screenshot of the Snyk page for movingpandas. It shows that the repository has a README file, contributing file, code of conduct. It also shows that it has 30 contributors and no funding. The package health score is 78/100." +msgstr "" + +#: ../../documentation/repository-files/intro.md:32 +msgid "Screenshot showing [SNYK](https://snyk.io/advisor/python/movingpandas) package health for moving pandas. Notice both platforms look for a README file. *(screen shot taken Nov 23 2022)*" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:8 +msgid "License files for scientific Python open source software" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:10 +msgid "Want to learn how to add a license file to your GitHub repository? Check out this lesson." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:17 +msgid "What is a Open Source License file?" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:19 +msgid "When we talk about LICENSE files, we are referring to a file in your GitHub or GitLab repository that contains legally binding language that describes to your users how they can legally use (and not use) your package." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:23 +msgid "Why licenses are important" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:25 +msgid "A license file is important for all open source projects because it protects both you as a maintainer and your users. The license file helps your users and the community understand:" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:27 +msgid "How they can use your software" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:28 +msgid "Whether the software can be reused or adapted for other purposes" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:29 +msgid "How people can contribute to your project" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:31 +msgid "and more." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:33 +msgid "[Read more about why license files are critical in protecting both you as a maintainer and your users of your scientific Python open source package.](https://opensource.guide/legal/#just-give-me-the-tldr-on-what-i-need-to-protect-my-project)" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:35 +msgid "Where to store your license" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:37 +msgid "Your `LICENSE` file should be stored at root of your GitHub / GitLab repository." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:39 +msgid "Some maintainers customize the language in their license files for specific reasons. However, if you are just getting started, we suggest that you select a permissive license and then use the legal language templates provided both by GitHub and/or the [choosealicense.com](https://choosealicense.com/) website." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:42 +msgid "Licenses are legally binding, as such you should avoid trying to create your own license unless you have the guidance of legal council." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:44 +msgid "Use open permissive licenses when possible" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:46 +msgid "We generally suggest that you use a permissive, license that is [Open Software Initiative (OSI) approved](https://opensource.org/licenses/). If you are [submitting your package to pyOpenSci for peer review](https://www.pyopensci.org/about-peer-review/index.html), then we require an OSI approved license." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:50 +msgid "Copyleft licenses" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:51 +msgid "The other major category of licenses are [\"copyleft\" licenses](https://en.wikipedia.org/wiki/Copyleft). Copyleft licenses require people that use your work to redistribute it with the same (or greater) rights to modify, copy, share, and redistribute it. In other words, copyleft licenses prohibit someone taking your work, making a proprietary version of it, and redistributing it without providing the source code so others can do the same. Copyleft licenses are \"sticky\" in that they are designed to ensure that more free software is created." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:56 +msgid "The difference between copyleft and permissive licenses is an important cultural divide in free and open source software (e.g., see {footcite}`hunterReclaimingComputingCommons2016`, {footcite}`gnuprojectWhatFreeSoftware2019`, {footcite}`gnuprojectWhatCopyleft2022`). It is important to understand this difference when choosing your license. Copyleft licenses represents the \"free\" part of \"free and open source software\". Free and open source software is intrinsically political, and it is important to be aware of power dynamics in computing as well as the practical problems of license compatibility (discussed below)." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:61 +msgid "How to choose a license" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:63 +msgid "To select your license, we suggest that you use GitHub's [Choose a License tool](https://choosealicense.com/)." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:66 +msgid "If you choose your license when creating a new GitHub repository, you can also automatically get a text copy of the license file to add to your repository. However in some cases the license that you want is not available through that online process." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:71 +msgid "License recommendations from the SciPy package" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:72 +msgid "[The SciPy documentation has an excellent overview of licenses.](https://docs.scipy.org/doc/scipy/dev/core-dev/index.html#licensing). One of the key elements that these docs recommend is ensuring that the license that you select is compatible with licenses used in many parts of the scientific Python ecosystem. Below is a highlight of this text which outlines license that are compatible with the modified BSD license that SciPy uses." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:78 +msgid "Other licenses that are compatible with the modified BSD license that SciPy uses are 2-clause BSD, MIT and PSF. Incompatible licenses are GPL, Apache and custom licenses that require attribution/citation or prohibit use for commercial purposes." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:80 +msgid "If your primary goal is for your code to be used by other, major packages in the scientific ecosystem, we also recommend that you consider using either BSD or MIT as your license. If you are unsure, the MIT license tends to be a simpler easier-to-understand option." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:85 +msgid "Important: make sure that you closely follow the guidelines outlines by the License that you chose" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:87 +msgid "Every license has different guidelines in terms of what code you can use in your package and also how others can (or can not) use the code in your package." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:90 +msgid "If you borrow code from other tools or online sources, make sure that the license for the code that you are using also complies with the license that you selected for your package." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:94 +msgid "A useful way to think about license compatibility is the distinction between **\"inbound\"** and **\"outbound\"** compatibility. \"Inbound\" licenses are those that cover the software you plan to include in your package. Your package is protected by an \"outbound\" license." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:98 +msgid "**Permissive licenses** like BSD and MIT have few **outbound** restrictions - they can be used in any way by downstream consumers, including making them proprietary. This is why they are favored by many businesses and large packages that want to be adopted by businesses. Permissive licenses have more **inbound** restrictions - they can't use software that requires more freedoms to be preserved than they do, like copyleft licenses. A package licensed under MIT needs to take special care when including or modifying a package licensed under the GPL-3." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:103 +msgid "**Copyleft licenses** like GPL-3 have more **outbound** restrictions - they require more of packages that include, use, modify, and reproduce them. This is the purpose of copyleft licenses, to ensure that derivative works remain free and open source. They have fewer **inbound** restrictions - a GPL-3 licensed package can include any other permissively licensed and most copyleft licensed packages." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:71 +msgid "Compatible" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:71 +msgid "Dependency
(\"Inbound\")" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:71 +msgid "Your Package" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:71 +msgid "Downstream Package
(\"Outbound\")" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:71 +msgid "" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:71 +msgid "Permissive" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:71 +msgid "" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:71 +msgid "Copyleft" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:118 +msgid "An example of how a license determine how code can be reused" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:121 +msgid "Let's use StackOverflow as an example that highlights how a license determines how code can or can not be used." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:123 +msgid "[Stack Overflow uses a Creative Commons Share Alike license.](https://stackoverflow.com/help/licensing). The sharealike license requires you to use the same sharealike license when you reuse any code from Stack Overflow." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:125 +msgid "This means that from a legal perspective, if you copy code from the Stack Overflow website and use it in your package that is licensed differently, say with a MIT license, you are violating Stack Overflow's license requirements! This would not be true with a GPL licensed package. `GPL-3` packages can include code licensed by `CC-BY-SA` {footcite}`creativecommonsShareAlikeCompatibilityGPLv32015`." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:128 +msgid "🚨 Proceed with caution! 🚨" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:131 +msgid "What about software citation?" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:133 +msgid "While many permissive licenses do not require citation we STRONG encourage that you cite all software that you use in papers, blogs and other publications. You tell your users how to cite your package by using a [citation.cff file](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files). We will cover this topic when we talk about creating DOI's for your package using Zenodo." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:141 +msgid "References" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:3 +msgid "README File Guidelines and Resources" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:5 +msgid "Your **README.md** file should be located in the root of your GitHub repository. The **README.md** file is important as it is often the first thing that someone sees before they install your package." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:9 +msgid "The README.md file is the landing page of:" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:11 +msgid "Your package as it appears on a repository site such as PyPI or Anaconda.org" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:12 +msgid "Your package's GitHub repository" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:14 +msgid "Your README.md file is also used as a measure of package and community health on sites such as:" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:17 +msgid "[GitHub community health for MovingPandas (available for all repositories)](https://github.com/movingpandas/movingpandas/community) and [Snyk - MovingPandas example](https://snyk.io/advisor/python/movingpandas)" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:19 +msgid "README landing page screenshot for the Pandera package. It has the Pandera logo at the top - which has two arrows in a chevron pattern pointing downward within a circle. Subtitle is statistical data testing toolkit. A data validation library for scientists, engineering, and analytics seeking correctness. Below that are a series of badges including CI tests passing, docs passing, version of Pandera on pypi (0.13.4), MIT license and that it has been pyOpenSci peer reviewed. There are numerous badges below that. Finally below the badges the text says, Pandera provides a flexible and expressive API for performing data validation on dataframe-like objects to make data processing pipelines more readable and robust." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:25 +msgid "Your GitHub repository landing page highlights the README.md file. Here you can see the README.md file for the pyOpenSci package [Pandera](https://github.com/unionai-oss/pandera). *(screen shot taken Nov 23 2022)*" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:28 +msgid "Thus, it is important that you spend some time up front creating a high quality **README.md** file for your Python package." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:32 +msgid "An editor or the editor in chief will ask you to revise your README file before a review begins if it does not meet the criteria specified below." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:35 +msgid "Please go through this list before submitting your package to pyOpenSci" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:52 +msgid "What your README.md file should contain" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:54 +msgid "Your **README.md** file should contain the following things (listed from top to bottom):" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:56 +msgid "✔️ Your package's name" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:58 +msgid "Ideally your GitHub repository's name is also the name of your package. The more self explanatory that name is, the better." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:61 +msgid "✔️ Badges for current package version, continuous integration and test coverage" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:63 +msgid "Badges are a useful way to draw attention to the quality of your project. Badges assure users that your package is well-designed, tested, and maintained. They are also a useful maintenance tool to evaluate if things are building properly. A great example of this is adding a [Read the Docs status badge](https://docs.readthedocs.io/en/stable/badges.html) to your README.md file to quickly see when the build on that site fails." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:69 +msgid "It is common to provide a collection of badges towards the top of your README file for others to quickly browse." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:72 +msgid "Some badges that you might consider adding to your README file include:" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:74 +msgid "Current version of the package on PyPI / Anaconda.org" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:76 +msgid "Example: [![PyPI version shields.io](https://img.shields.io/pypi/v/pandera.svg)](https://pypi.org/project/pandera/)" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:76 +msgid "PyPI version shields.io" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:78 +msgid "Status of tests (pass or fail) - Example: [![CI Build](https://github.com/pandera-dev/pandera/workflows/CI%20Tests/badge.svg?branch=main)](https://github.com/pandera-dev/pandera/actions?query=workflow%3A%22CI+Tests%22+branch%3Amain)" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:78 +msgid "CI Build" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:80 +msgid "Documentation build - Example: ![Docs Building](https://github.com/pyOpenSci/python-package-guide/actions/workflows/build-book.yml/badge.svg)" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:80 +msgid "Docs Building" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:82 +msgid "DOI (for citation) Example: [![DOI](https://zenodo.org/badge/556814582.svg)](https://zenodo.org/badge/latestdoi/556814582)" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:82 +msgid "DOI" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:85 +msgid "Once you package is accepted to pyOpenSci, we will provide you with a badge to add to your repository that shows that it has been reviewed. [![pyOpenSci](https://pyopensci.org/badges/peer-reviewed.svg)](https://github.com/pyOpenSci/software-review/issues/12)" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:85 +msgid "pyOpenSci" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:92 +msgid "Beware of the overuse of badges! There is such a thing as too much of a good thing (which can overload a potential user!)." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:95 +msgid "✔️ A short, easy-to-understand description of what your package does" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:97 +msgid "At the top of your README file you should have a short, easy-to-understand, 1-3 sentence description of what your package does. This section should clearly state your goals for the package. The language in this description should use less technical terms so that a variety of users with varying scientific (and development) backgrounds can understand it." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:103 +msgid "In this description, it's useful to let users know how your package fits within the broader scientific Python package ecosystem. If there are other similar packages or complementary package mentions them here in 1-2 sentences." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:108 +msgid "Consider writing for a high school level (or equivalent) level. This level of writing is often considered an appropriate level for scientific content that serves a variety of users with varying backgrounds." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:112 +msgid "The goal of this description is to maximize accessibility of your **README** file." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:116 +msgid "✔️ Installation instructions" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:118 +msgid "Include instructions for installing your package. If you have published the package on both PyPI and Anaconda.org, be sure to include instructions for both." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:121 +msgid "✔️ Document any additional setup required" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:123 +msgid "Add any additional setup required such as authentication tokens, to get started using your package. If setup is complex, consider linking to an installation page in your online documentation here rather than over complicating your README file." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:128 +msgid "✔️ Brief demonstration of how to use the package" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:130 +msgid "This description ideally includes a brief, quick start code example that shows a user how to get started using your package." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:133 +msgid "✔️ Descriptive links to package documentation, short tutorials" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:135 +msgid "Include descriptive links to:" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:137 +msgid "The package's documentation page." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:138 +msgid "Short tutorials that demonstrate application of your package." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:140 +msgid "Too Much Of A Good Thing" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:143 +msgid "Try to avoid including several tutorials in the README.md file itself. This too will overwhelm the user with information." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:145 +msgid "A short quick-start code example that shows someone how to use your package is plenty of content for the README file. All other tutorials and documentation should be presented as descriptive links." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:151 +msgid "✔️ A Community Section with Links to Contributing Guide, Code of Conduct" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:153 +msgid "Use your README.md file to direct users to more information on:" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:155 +msgid "Contributing to your package" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:156 +msgid "Development setup for more advanced technical contributors" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:157 +msgid "Your code of conduct" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:158 +msgid "Licensing information" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:160 +msgid "All of the above files are important for building community around your project." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:163 +msgid "✔️ Citation information" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:165 +msgid "Finally be sure to include instructions on how to cite your package. Citation should include the DOI that you want used when citing your package, and any language that you'd like to see associated with the citation." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:169 +msgid "README Resources" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:173 +msgid "Below are some resources on creating great README.md files that you might find helpful." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:176 +msgid "[How to Write a Great README - Bane Sullivan](https://github.com/banesullivan/README)" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:177 +msgid "[Art of README - Kira (@hackergrrl)](https://github.com/hackergrrl/art-of-readme)" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:1 +msgid "Create tutorials in your Python package documentation" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:6 +msgid "Your package should have tutorials that make it easy for a user to get started using your package. Ideally, those tutorials also can be run from start to finish providing a second set of checks (on top of your test suite) to your package's code base." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:11 +msgid "On this page, we review two Sphinx extensions (`sphinx-gallery` and `nbsphinx`) that allow you to create reproducible tutorials that are run when your Sphinx documentation builds." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:15 +msgid "Create Python package tutorials that run when you build your docs" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:17 +msgid "Adding well constructed tutorials to your package will make it easier for someone new to begin using your package." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:20 +msgid "There are two Sphinx tools that make it easy to add tutorials to your package:" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:22 +msgid "[Sphinx Gallery](https://sphinx-gallery.github.io/stable/index.html) and" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:23 +msgid "[NbSphinx](https://nbsphinx.readthedocs.io/en/latest/)" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:25 +msgid "Both of these tools act as Sphinx extensions and:" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:27 +msgid "Support creating a gallery type page in your Sphinx documentation where users can explore tutorials via thumbnails." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:28 +msgid "Run the code in your tutorials adding another level of \"testing\" for your package as used." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:29 +msgid "Render your tutorials with Python code and plot outputs" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:31 +msgid "[sphinx gallery:](https://sphinx-gallery.github.io/stable/index.html)" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:33 +msgid "If you prefer to write your tutorials using Python **.py** scripts, you may enjoy using Sphinx gallery. Sphinx gallery uses **.py** files with text and code sections that mimic the Jupyter Notebook format. When you build your documentation, the gallery extension:" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:38 +msgid "Runs the code in each tutorial. Running your tutorial like this acts as a check to ensure your package's functions, classes, methods, and attributes (ie the API) are working as they should." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:39 +msgid "Creates a downloadable Jupyter Notebook **.ipynb** file and a **.py** script for your tutorial that a user can quickly download and run." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:40 +msgid "Creates a rendered **.html** page with the code elements and code outputs in a user-friendly tutorial gallery." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:41 +msgid "Creates a gallery landing page with visual thumbnails for each tutorial that you create." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:44 +msgid "Image showing the gallery output provided by sphinx-gallery where each tutorial is in a grid and the tutorial thumbnails are created from a graphic in the tutorial." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:50 +msgid "`sphinx-gallery` makes it easy to create a user-friendly tutorial gallery. Each tutorial has a download link where the user can download a **.py** file or a Jupyter Notebook. And it renders the tutorials in a user-friendly grid." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:54 +msgid "Below you can see what a tutorial looks like created with sphinx-gallery." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:56 +msgid "Image showing ta single tutorial from Sphinx gallery. The tutorial shows a simple matplotlib created plot and associated code." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:62 +msgid "`sphinx-gallery` tutorials by default include download links for both the python script (**.py** file) and a Jupyter notebook (**.ipynb** file) at the bottom." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:66 +msgid "Sphinx Gallery benefits" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:67 +msgid "easy-to-download notebook and .py outputs for each tutorials." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:68 +msgid ".py files are easy to work with in the GitHub pull request environment." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:69 +msgid "Nice gridded gallery output." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:70 +msgid "Build execution time data per tutorial. [Example](https://sphinx-gallery.github.io/stable/auto_examples/sg_execution_times.html)" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:72 +msgid "Sphinx gallery challenges" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:74 +msgid "The downsides of using Sphinx gallery include:" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:76 +msgid "the **.py** files can be finicky to configure, particularly if you have matplotlib plot outputs." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:78 +msgid "For example: To allow for plots to render, you need to name each file with `plot_` at the beginning." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:81 +msgid "Many users these days are used to working in Jupyter Notebooks. .py may be slightly less user friendly to work with" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:83 +msgid "These nuances can make it challenging for potential contributors to add tutorials to your package. This can also present maintenance challenge." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:86 +msgid "Add about the gallery setup:" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:93 +msgid "File directory structure:" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:114 +msgid "[nbsphinx - tutorials using Jupyter Notebooks](https://nbsphinx.readthedocs.io/en/latest/)" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:116 +msgid "If you prefer to use Jupyter Notebooks to create tutorials you can use nbsphinx. nbsphinx operates similarly to Sphinx gallery in that:" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:119 +msgid "It runs your notebooks and produces outputs in the rendered tutorials" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:121 +msgid "Pro/con By default it does not support downloading of **.py** and **.ipynb** files. However you can add a [link to the notebook at the top of the page with some additional conf.py settings (see: epilog settings)](https://nbsphinx.readthedocs.io/en/0.8.10/prolog-and-epilog.html)" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:125 +msgid "Image showing the gallery output provided by nbsphinx using the sphinx-gallery front end interface." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:131 +msgid "`nbsphinx` can be combined with Sphinx gallery to create a gallery of tutorials. However, rather than rendering the gallery as a grid, it lists all of the gallery elements in a single column." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:1 +msgid "Document the code in your package's API using docstrings" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:3 +msgid "What is an API?" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:5 +msgid "API stands for **A**pplied **P**rogramming **I**nterface. When discussed in the context of a (Python) package, the API refers to the functions, classes, methods, and attributes that a package maintainer creates for users." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:9 +msgid "A simple example of a package API element: For instance, a package might have a function called `add_numbers()` that adds up a bunch of numbers. To add up numbers, you as the user simply call `add_numbers(1,2,3)` and the package function calculates the value and returns `6`. By calling the `add_numbers` function, you are using the package's API." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:15 +msgid "Package APIs consist of functions, classes, methods and attributes that create a user interface." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:17 +msgid "What is a docstring and how does it relate to documentation?" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:19 +msgid "In Python, a docstring refers to text in a function, method or class that describes what the function does and its inputs and outputs. Python programmers usually refer to the inputs to functions as [\"parameters\"](https://docs.python.org/3/glossary.html#term-parameter) or [\"arguments\"](https://docs.python.org/3/faq/programming.html#faq-argument-vs-parameter), and the outputs are often called \"return values\"" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:22 +msgid "The docstring is thus important for:" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:24 +msgid "When you call `help()` in Python, for example, `help(add_numbers)` will show the text of the function's docstring. The docstring thus helps a user better understand how to apply the function more effectively to their workflow." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:25 +msgid "When you build your package's documentation, the docstrings can also be used to automatically create full API documentation that provides a clean view of all its functions, classes, methods, and attributes." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:28 +msgid "Example API Documentation for all functions, classes, methods, and attributes in a package." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:29 +msgid "[View example high-level API documentation for the Verde package. This page lists every function and class in the package along with a brief explanation of what it does](https://www.fatiando.org/verde/latest/api/index.html)" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:30 +msgid "[You can further dig down to see what a specific function does within the package by clicking on an API element](https://www.fatiando.org/verde/latest/api/generated/verde.grid_coordinates.html#verde.grid_coordinates)" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:33 +msgid "Python package API documentation" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:35 +msgid "If you have a descriptive docstring for every user-facing class, method, attribute and/or function in your package (_within reason_), then your package's API is considered well-documented." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:38 +msgid "In Python, this means that you need to add a docstring for every user-facing class, method, attribute and/or function in your package (_within reason_) that:" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:42 +msgid "Explains what the function, method, attribute, or class does" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:43 +msgid "Defines the `type` inputs and outputs (ie. `string`, `int`, `np.array`)" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:44 +msgid "Explains the expected output `return` of the object, method or function." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:47 +msgid "Three Python docstring formats and why we like NumPy style" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:49 +msgid "There are several Python docstring formats that you can choose to use when documenting your package including:" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:52 +msgid "[NumPy-style](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard)" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:53 +msgid "[google style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:54 +msgid "[reST style](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html)" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:58 +msgid "We suggest using [NumPy-style docstrings](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard) for your Python documentation because:" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:61 +msgid "NumPy style docstrings are core to the scientific Python ecosystem and defined in the [NumPy style guide](https://numpydoc.readthedocs.io/en/latest/format.html). Thus you will find them widely used there." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:62 +msgid "The Numpy style docstring is simplified and thus easier to read both in the code and when calling `help()` in Python. In contrast, some feel that reST style docstrings are harder to quickly scan, and can take up more lines of code in modules." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:65 +msgid "If you are using NumPy style docstrings, be sure to include the [sphinx napoleon extension](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html) in your documentation `conf.py` file. This extension allows Sphinx to properly read and format NumPy format docstrings." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:70 +msgid "Docstring examples Better and Best" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:72 +msgid "Below is a good example of a well-documented function. Notice that this function's docstring describes the function's inputs and the function's output (or return value). The initial description of the function is short (one line). Following that single-line description, there is a slightly longer description of what the function does (2 to 3 sentences). The return of the function is also specified." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:106 +msgid "Best: a docstring with example use of the function" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:108 +msgid "This example contains an example of using the function that is also tested in sphinx using [doctest](https://docs.python.org/3/library/doctest.html)." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:159 +msgid "Using the above NumPy format docstring in sphinx, the autodoc extension will create the about documentation section for the `extent_to_json` function. The output of the `es.extent_to_json(rmnp)` command can even be tested using doctest adding another quality check to your package." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:165 +msgid "Using doctest to run docstring examples in your package's methods and functions" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:170 +msgid "Above, we provided some examples of good, better, best docstring formats. If you are using Sphinx to create your docs, you can add the [doctest](https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html) extension to your Sphinx build. Doctest provides an additional check for docstrings with example code in them. Doctest runs the example code in your docstring `Examples` checking that the expected output is correct. Similar to running tutorials in your documentation, `doctest` can be a useful step that assures that your package's code (API) runs as you expect it to." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:177 +msgid "It's important to keep in mind that examples in your docstrings help users using your package. Running `doctest` on those examples provides a check of your package's API. The doctest ensures that the functions and methods in your package run as you expect them to. Neither of these items replace a separate, stand-alone test suite that is designed to test your package's core functionality across operating systems and Python versions." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:185 +msgid "Below is an example of a docstring with an example. doctest will run the example below and test that if you provide `add_me` with the values 1 and 3 it will return 4." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:218 +msgid "Adding type hints to your docstrings" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:220 +msgid "In the example above, you saw the use of numpy-style docstrings to describe data types that are passed into functions as parameters or into classes as attributes. In a numpy-style docstring you add those types in the Parameters section of the docstring. Below you can see that the parameter `num1` and `num2` should both be a Python `int` (integer) value." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:235 +msgid "Describing the expected data type that a function or method requires helps users better understand how to call a function or method." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:238 +msgid "Type-hints add another layer of type documentation to your code. Type-hints make it easier for new developers, your future self or contributors to get to know your code base quickly." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:242 +msgid "Type hints are added to the definition of your function. In the example below, the parameters aNum and aNum2 are defined as being type = int (integer)." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:249 +msgid "You can further describe the expected function output using `->`. Below the output of the function is also an int." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:257 +msgid "Why use type hints" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:259 +msgid "Type hints:" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:261 +msgid "Make development and debugging faster," +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:262 +msgid "Make it easier for a user to see the data format inputs and outputs of methods and functions," +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:263 +msgid "Support using static type checking tools such as [`mypy`](https://mypy-lang.org/) which will check your code to ensure types are correct." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:265 +msgid "You should consider adding type hinting to your code if:" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:267 +msgid "Your package performs data processing," +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:268 +msgid "You use functions that require complex inputs" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:269 +msgid "You want to lower the entrance barrier for new contributors to help you with your code." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:271 +msgid "Beware of too much type hinting" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:274 +msgid "As you add type hints to your code consider that in some cases:" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:276 +msgid "If you have a complex code base, type hints may make code more difficult to read. This is especially true when a parameter’s input takes multiple data types and you list each one." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:277 +msgid "Writing type hints for simple scripts and functions that perform obvious operations don't make sense." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:280 +msgid "Gradually adding type hints" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:282 +msgid "Adding type hints can take a lot of time. However, you can add type hints incrementally as you work on your code." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:286 +msgid "Adding type hints is also a great task for new contributors. It will help them get to know your package's code and structure better before digging into more complex contributions." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:1 +msgid "Create User Facing Documentation for your Python Package" +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:14 +msgid "Core components of user-facing Python package documentation" +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:15 +msgid "Below we break documentation into two broad types." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:17 +msgid "**User-facing documentation** refers to documentation that describes the way the tools within a package are broadly used in workflows. **API documentation** refers to documentation of functions, classes, methods, and attributes in your code and is written at a more granular level. This documentation is what a user sees when they type `help(function-name)`." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:23 +msgid "Your user-facing documentation for your Python package should include several core components." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:26 +msgid "**Documentation Website:** This refers to easy-to-read documentation that helps someone use your package. This documentation should help users both install and use your package." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:27 +msgid "**Short Tutorials:** Your user-facing documentation should also include [**short tutorials** that showcase core features of your package](create-package-tutorials)." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:28 +msgid "**Package Code / API documentation:** You package's functions, classes, methods, and attributes (the API) should also be documented. API documentation can be generated from [docstrings](https://pandas.pydata.org/docs/development/contributing_docstring.html) found in your code. Ideally, you have docstrings for all user-facing functions, classes, and methods in your Python package. [We discuss code documentation and docstrings in greater detail here.](document-your-code-api-docstrings)" +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:32 +msgid "Write usable documentation" +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:34 +msgid "User-facing documentation should be published on a easy-to-navigate website. The documentation should be written keeping in mind that users may not be developers or expert-level programmers. Rather, the language that you use in your documentation should not be highly technical." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:39 +msgid "To make the language of your documentation more accessible to a broader audience:" +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:42 +msgid "Whenever possible, define technical terms and jargon." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:43 +msgid "Consider writing instructions for a high-school level reader." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:44 +msgid "Include step-by-step code examples, tutorials or vignettes that support getting started using your package." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:46 +msgid "Four elements of a good open source documentation landing page" +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:48 +msgid "To make it easy for users to find what they need quickly, consider adding quick links on your package's landing page to the following elements:" +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:52 +msgid "**Getting started:** This section should provide the user with a quick start for installing your package. A small example of how to use the package is good to have here as well. Or you can link to useful tutorials in the get started section." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:53 +msgid "**About:** Describe your project, stating its goals and its functionality." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:54 +msgid "**Community:** Instructions for how to help and/or get involved. This might include links to your issues (if that is where you let users ask questions) or the discussion part of your GitHub repo. This section might include a development guide for those who might contribute to your package." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:55 +msgid "**API Documentation:** This is the detailed project documentation. Here you store documentation for your package's API including all user-facing functions, classes, methods, and attributes as well as any additional high level discussion that will help people use your package." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:58 +msgid "Image showing the landing page for GeoPandas documentation which has 4 sections including Getting started, Documentation, About GeoPandas, Community." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:64 +msgid "The documentation landing page of GeoPandas, a spatial Python library, has the 4 element specified above. Notice that the landing page is simple and directs users to each element using a Sphinx card." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:67 +msgid "NOTE: in many cases you can include your **README** file and your **CONTRIBUTING** files in your documentation given those files may have some of the components listed above." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:71 +msgid "You can include files in Sphinx using the include directive. Below is an example of doing this using `myst` syntax." +msgstr "" + +#: ../../documentation/write-user-documentation/intro.md:1 +msgid "Writing user-facing documentation for your Python package" +msgstr "" + +#: ../../documentation/write-user-documentation/intro.md:3 +msgid "This section walks you through best practices for with writing documentation for your Python package." +msgstr "" + +#: ../../documentation/write-user-documentation/intro.md:6 +msgid "We talk about the elements that you should consider adding to your documentation, the different types of users who might read your documentation and how to create tutorials for your package." +msgstr "" + +#: ../../documentation/write-user-documentation/intro.md:10 +msgid "Here we also cover sphinx extensions that you can user to make documentation easier such as:" +msgstr "" + +#: ../../documentation/write-user-documentation/intro.md:13 +msgid "autodoc to automagically populate documentation for your code's functions, classes, methods and attributes (API documentation) and" +msgstr "" + +#: ../../documentation/write-user-documentation/intro.md:15 +msgid "sphinx gallery for tutorials." +msgstr "" diff --git a/locales/templates/LC_MESSAGES/index.pot b/locales/templates/LC_MESSAGES/index.pot new file mode 100644 index 00000000..5c423eac --- /dev/null +++ b/locales/templates/LC_MESSAGES/index.pot @@ -0,0 +1,407 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2025, pyOpenSci +# This file is distributed under the same license as the pyOpenSci Python Package Guide package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: pyOpenSci Python Package Guide \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-04-30 18:44-0600\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../index.md:292 +msgid "Tutorials" +msgstr "" + +#: ../../index.md:299 +msgid "Packaging" +msgstr "" + +#: ../../index.md:148 +#: ../../index.md:307 +msgid "Documentation" +msgstr "" + +#: ../../index.md:196 +#: ../../index.md:316 +msgid "Tests" +msgstr "" + +#: ../../index.md:316 +msgid "Testing" +msgstr "" + +#: ../../index.md:325 +msgid "CI/CD" +msgstr "" + +#: ../../index.md:325 +msgid "Continuous Integration" +msgstr "" + +#: ../../index.md:1 +msgid "pyOpenSci Python Package Guide" +msgstr "" + +#: ../../index.md:3 +msgid "We support the Python tools that scientists need to create open science workflows." +msgstr "" + +#: ../../index.md:20 +msgid "![GitHub release (latest by date)](https://img.shields.io/github/v/release/pyopensci/python-package-guide?color=purple&display_name=tag&style=plastic) [![](https://img.shields.io/github/stars/pyopensci/python-package-guide?style=social)](https://github.com/pyopensci/contributing-guide) [![DOI](https://zenodo.org/badge/556814582.svg)](https://zenodo.org/badge/latestdoi/556814582)" +msgstr "" + +#: ../../index.md:20 +msgid "GitHub release (latest by date)" +msgstr "" + +#: ../../index.md:20 +msgid "DOI" +msgstr "" + +#: ../../index.md:27 +msgid "About this guide" +msgstr "" + +#: ../../index.md:29 +msgid "Image with the pyOpenSci flower logo in the upper right hand corner. The image shows the packaging lifecycle. The graphic shows a high level overview of the elements of a Python package. The inside circle has 5 items - user documentation, code/api, test suite, contributor documentation, project metadata / license / readme. In the middle of the circle is says maintainers and has a small icon with people. On the outside circle there is an arrow and it says infrastructure." +msgstr "" + +#: ../../index.md:35 +msgid "This guide will help you:" +msgstr "" + +#: ../../index.md:37 +msgid "Learn how to create a Python package from start to finish" +msgstr "" + +#: ../../index.md:38 +msgid "Understand the broader Python packaging tool ecosystem" +msgstr "" + +#: ../../index.md:39 +msgid "Navigate and make decisions around tool options" +msgstr "" + +#: ../../index.md:40 +msgid "Understand all of the pieces of creating and maintaining a Python package" +msgstr "" + +#: ../../index.md:42 +msgid "You will also find best practice recommendations and curated lists of community resources surrounding packaging and package documentation." +msgstr "" + +#: ../../index.md:46 +msgid "Todo" +msgstr "" + +#: ../../index.md:47 +msgid "TODO: change the navigation of docs to have a" +msgstr "" + +#: ../../index.md:49 +msgid "user documentation contributor / maintainer documentation" +msgstr "" + +#: ../../index.md:51 +msgid "development guide" +msgstr "" + +#: ../../index.md:52 +msgid "contributing guide" +msgstr "" + +#: ../../index.md:54 +msgid "Community docs" +msgstr "" + +#: ../../index.md:55 +msgid "readme, coc, license" +msgstr "" + +#: ../../index.md:57 +msgid "Publish your docs" +msgstr "" + +#: ../../index.md:59 +msgid "_new_ Tutorial Series: Create a Python Package" +msgstr "" + +#: ../../index.md:61 +msgid "The first round of our community-developed, how to create a Python package tutorial series for scientists is complete! Join our community review process or watch development of future tutorials in our [GitHub repo here](https://github.com/pyOpenSci/python-package-guide)." +msgstr "" + +#: ../../index.md:71 +msgid "✿ Create a Package Tutorials ✿" +msgstr "" + +#: ../../index.md:75 +msgid "[What is a Python package?](/tutorials/intro)" +msgstr "" + +#: ../../index.md:76 +msgid "[Create a Python package](/tutorials/installable-code)" +msgstr "" + +#: ../../index.md:77 +msgid "[Publish your package to (test) PyPI](/tutorials/publish-pypi)" +msgstr "" + +#: ../../index.md:78 +msgid "[Publish your package to conda-forge](/tutorials/publish-conda-forge)" +msgstr "" + +#: ../../index.md:83 +msgid "✿ Package Metadata Tutorials ✿" +msgstr "" + +#: ../../index.md:87 +msgid "[How to add a README file](/tutorials/add-readme)" +msgstr "" + +#: ../../index.md:88 +msgid "[How to add metadata to a pyproject.toml file for publication to PyPI.](/tutorials/pyproject-toml.md)" +msgstr "" + +#: ../../index.md:93 +msgid "✿ Packaging Tool Tutorials ✿" +msgstr "" + +#: ../../index.md:97 +msgid "[Introduction to Hatch](/tutorials/get-to-know-hatch)" +msgstr "" + +#: ../../index.md:102 +msgid "✿ Reference Guides ✿" +msgstr "" + +#: ../../index.md:106 +msgid "[Command Line Reference Guide](/tutorials/command-line-reference)" +msgstr "" + +#: ../../index.md:111 +msgid "Python Packaging for Scientists" +msgstr "" + +#: ../../index.md:113 +msgid "Learn about Python packaging best practices. You will also get to know the the vibrant ecosystem of packaging tools that are available to help you with your Python packaging needs." +msgstr "" + +#: ../../index.md:122 +msgid "✨ Create your package ✨" +msgstr "" + +#: ../../index.md:126 +msgid "[Package file structure](/package-structure-code/python-package-structure)" +msgstr "" + +#: ../../index.md:127 +msgid "[Package metadata / pyproject.toml](package-structure-code/pyproject-toml-python-package-metadata.md)" +msgstr "" + +#: ../../index.md:128 +msgid "[Build your package (sdist / wheel)](package-structure-code/python-package-distribution-files-sdist-wheel.md)" +msgstr "" + +#: ../../index.md:129 +msgid "[Declare dependencies](package-structure-code/declare-dependencies.md)" +msgstr "" + +#: ../../index.md:130 +msgid "[Navigate the packaging tool ecosystem](package-structure-code/python-package-build-tools.md)" +msgstr "" + +#: ../../index.md:131 +msgid "[Non pure Python builds](package-structure-code/complex-python-package-builds.md)" +msgstr "" + +#: ../../index.md:136 +msgid "✨ Publish your package ✨" +msgstr "" + +#: ../../index.md:140 +msgid "Gain a better understanding of the Python packaging ecosystem Learn about best practices for:" +msgstr "" + +#: ../../index.md:143 +msgid "[Package versioning & release](/package-structure-code/python-package-versions.md)" +msgstr "" + +#: ../../index.md:144 +msgid "[Publish to PyPI & Conda-forge](/package-structure-code/publish-python-package-pypi-conda.md)" +msgstr "" + +#: ../../index.md:157 +msgid "✨ Write The Docs ✨" +msgstr "" + +#: ../../index.md:160 +msgid "[Create documentation for your users](/documentation/write-user-documentation/intro)" +msgstr "" + +#: ../../index.md:161 +msgid "[Core files to include in your package repository](/documentation/repository-files/intro)" +msgstr "" + +#: ../../index.md:162 +msgid "[Write tutorials to show how your package is used](/documentation/write-user-documentation/create-package-tutorials)" +msgstr "" + +#: ../../index.md:167 +msgid "✨ Developer Docs ✨" +msgstr "" + +#: ../../index.md:170 +msgid "[Create documentation for collaborating developers](/documentation/repository-files/contributing-file)" +msgstr "" + +#: ../../index.md:171 +msgid "[Write a development guide](/documentation/repository-files/development-guide)" +msgstr "" + +#: ../../index.md:176 +msgid "✨ Document For A Community ✨" +msgstr "" + +#: ../../index.md:179 +msgid "[Writing a README file](/documentation/repository-files/readme-file-best-practices)" +msgstr "" + +#: ../../index.md:180 +msgid "[Set norms with a Code of Conduct](/documentation/repository-files/code-of-conduct-file)" +msgstr "" + +#: ../../index.md:181 +msgid "[License your package](/documentation/repository-files/license-files)" +msgstr "" + +#: ../../index.md:186 +msgid "✨ Publish Your Docs ✨" +msgstr "" + +#: ../../index.md:189 +msgid "[How to publish your docs](/documentation/hosting-tools/intro)" +msgstr "" + +#: ../../index.md:190 +msgid "[Using Sphinx](/documentation/hosting-tools/intro)" +msgstr "" + +#: ../../index.md:191 +msgid "[Markdown, MyST, and ReST](/documentation/hosting-tools/myst-markdown-rst-doc-syntax)" +msgstr "" + +#: ../../index.md:192 +msgid "[Host your docs on Read The Docs or GitHub Pages](/documentation/hosting-tools/publish-documentation-online)" +msgstr "" + +#: ../../index.md:198 +msgid "*We are actively working on this section. [Follow development here.](https://github.com/pyOpenSci/python-package-guide)*" +msgstr "" + +#: ../../index.md:206 +msgid "✨ Tests for your Python package ✨" +msgstr "" + +#: ../../index.md:209 +msgid "[Intro to testing](tests/index.md)" +msgstr "" + +#: ../../index.md:210 +msgid "[Write tests](tests/write-tests)" +msgstr "" + +#: ../../index.md:211 +msgid "[Types of tests](tests/test-types)" +msgstr "" + +#: ../../index.md:216 +msgid "✨ Run your tests ✨" +msgstr "" + +#: ../../index.md:219 +msgid "[Run tests locally](tests/run-tests)" +msgstr "" + +#: ../../index.md:220 +msgid "[Run tests in CI](tests/tests-ci)" +msgstr "" + +#: ../../index.md:224 +msgid "Contributing" +msgstr "" + +#: ../../index.md:234 +msgid "✨ Code style & Format ✨" +msgstr "" + +#: ../../index.md:239 +msgid "[Code style](package-structure-code/code-style-linting-format.md)" +msgstr "" + +#: ../../index.md:244 +msgid "✨ Want to contribute? ✨" +msgstr "" + +#: ../../index.md:249 +msgid "We welcome contributions to this guide. Learn more about how you can contribute." +msgstr "" + +#: ../../index.md:255 +msgid "xkcd comic showing a stick figure on the ground and one in the air. The one on the ground is saying. `You're flying! how?` The person in the air replies `Python!` Below is a 3 rectangle comic with the following text in each box. Box 1 - I learned it last night. Everything is so simple. Hello world is just print hello world. Box 2 - the person on the ground says - come join us programming is fun again. It's a whole new world. But how are you flying? box 3 - the person flying says - i just typed import antigravity. I also sampled everything in the medicine cabinet. But i think this is the python. The person on the ground is saying - that's it?" +msgstr "" + +#: ../../index.md:261 +msgid "A community-created guidebook" +msgstr "" + +#: ../../index.md:263 +msgid "Every page in this guidebook goes through an extensive community review process. To ensure our guidebook is both beginner-friendly and accurate, we encourage reviews from a diverse set of pythonistas and scientists with a wide range of skills and expertise." +msgstr "" + +#: ../../index.md:266 +msgid "View guidebook contributors" +msgstr "" + +#: ../../index.md:274 +msgid "Who this guidebook is for" +msgstr "" + +#: ../../index.md:276 +msgid "This guidebook is for anyone interested in learning more about Python packaging. It is beginner-friendly and will provide:" +msgstr "" + +#: ../../index.md:278 +msgid "Beginning-to-end guidance on creating a Python package." +msgstr "" + +#: ../../index.md:279 +msgid "Resources to help you navigate the Python packaging ecosystem of tools and approaches to packaging." +msgstr "" + +#: ../../index.md:280 +msgid "A curated list of resources to help you get your package into documented, usable and maintainable shape." +msgstr "" + +#: ../../index.md:282 +msgid "Where this guide is headed" +msgstr "" + +#: ../../index.md:284 +msgid "If you have ideas of things you'd like to see here clarified in this guide, [we invite you to open an issue on GitHub.](https://github.com/pyOpenSci/python-package-guide/issues)." +msgstr "" + +#: ../../index.md:287 +msgid "If you have questions about our peer review process or packaging in general, you are welcome to use our [pyOpenSci Discourse forum](https://pyopensci.discourse.group/)." +msgstr "" + +#: ../../index.md:289 +msgid "This living Python packaging guide is updated as tools and best practices evolve in the Python packaging ecosystem. We will be adding new content over the next year." +msgstr "" diff --git a/locales/templates/LC_MESSAGES/messages.pot b/locales/templates/LC_MESSAGES/messages.pot new file mode 100644 index 00000000..351a7521 --- /dev/null +++ b/locales/templates/LC_MESSAGES/messages.pot @@ -0,0 +1,3648 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2025, pyOpenSci +# This file is distributed under the same license as the pyOpenSci Python Package Guide package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: pyOpenSci Python Package Guide \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-04-30 18:44-0600\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../package-structure-code/code-style-linting-format.md:1 +msgid "Python Package Code Style, Format and Linters" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:3 +#: ../../package-structure-code/publish-python-package-pypi-conda.md:12 +msgid "Take Aways" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:5 +msgid "pyOpenSci requires authors to follow PEP 8 code format guidelines" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:6 +msgid "Setting up a code formatters like Black and isort will help you enforce PEP 8 style guidelines and also consistent, readable code format" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:7 +msgid "Some commonly used tools are: Black, Isort, flake8, Ruff" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:8 +msgid "You can also setup pre-commit hooks which will run code formatters locally each time you make a commit." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:10 +msgid "[precommit.ci](https://pre-commit.ci/) is a bot that you can add to your GitHub repository. It will automagically apply code format to every PR using the tools specified in your pre-commit-config.yaml file. It can save significant time and make contributions easier for new contributors." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:11 +msgid "Automation is good! By making code quality tools care of your code, you can focus on structural and high values tasks." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:14 +msgid "Consistent code format and style is useful to both your package and across the scientific Python ecosystem because using similar formats makes code easier to read." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:18 +msgid "For instance, if you saw a sentence like this one without any spaces, or punctuation, it would take your brain longer to process it." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:25 +msgid "pyOpenSci peer review process requires that you to follow standard [Python PEP 8 format rules](https://peps.python.org/pep-0008/) as closely as you can." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:29 +msgid "pyOpenSci doesn't require you to use a specific code format tool. However, we do look for consistency and readability in code style. Below you will find a discussion of:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:33 +msgid "The benefits of using linters and code format tools in your workflow" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:34 +msgid "Some commonly used tools in the scientific Python space" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:35 +msgid "Setting up pre-commit hooks and the pre-commit.ci bot to make using code format tools in daily workflows and in pull requests on GitHub easier." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:38 +msgid "Use a code format tool (or tools) to make your life easier" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:40 +msgid "We suggest that you use a code format tool, or a set of format tools, because manually applying all of the PEP 8 format specifications is both time consuming for maintainers and can be a road block for potential new contributors. Code formatters will automagically reformat your code for you, adhering to PEP 8 standards and applying consistent style decisions throughout." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:46 +msgid "Setting up a code format suite of tools will:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:48 +msgid "Save you and your maintainer team time in fixing PEP 8 inconsistencies." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:49 +msgid "Ensure that format and style is consistent across your entire code-base." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:50 +msgid "Avoid lengthy discussions with contributors and other maintainers about personalized code format preferences during reviews." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:52 +msgid "Avoid pure visual edits in the code base so that code reviews focus on added value" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:54 +msgid "Many packages use a suite of tools to apply code format rules, taking the work out of manually implementing code format requirements." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:57 +msgid "Consistent code format across packages within the (scientific) Python ecosystem, will also broadly make code easier to scan, understand and contribute to." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:60 +msgid "Linting vs format and style" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:62 +msgid "Before we dive in let's get a few definitions out of the way." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:64 +msgid "Code Linting" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:66 +msgid "A code linter is a tool that will review your code and identify errors or issues. A linter typically does not modify your code. It will tell you what the error is and on what line it was discovered. Flake8, discussed below, is an example of a commonly-used code linter." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:71 +msgid "Code Formatters (and stylers)" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:73 +msgid "Code formatters will reformat your code for you. Python focused code formatters often follow PEP 8 standards. However, they also make stylistic decisions about code consistency." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:77 +msgid "Black is an example of a commonly-used code formatter. Black both applies PEP 8 standards while also making decisions about things like consistent use of double quotes for strings, and spacing of items in lists." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:81 +msgid "You will learn more about Black below." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:83 +msgid "Code linting, formatting and styling tools" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:85 +msgid "Black" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:87 +msgid "[Black](https://black.readthedocs.io/en/stable/) is a code formatter. Black will automagically (and _unapologetically_) fix spacing issues and ensure code format is consistent throughout your package. Black also generally adheres to PEP 8 style guidelines with some exceptions. A few examples of those exceptions are below:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:93 +msgid "Black defaults to a line length of 88 (79 + 10%) rather than the 79 character `PEP 8` specification. However, line length is a setting can be manually overwritten in your Black configuration." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:94 +msgid "Black will not adjust line length in your comments or docstrings." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:95 +msgid "This tool will not review and fix import order (you need `isort` or `ruff` to do that - see below)." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:98 +msgid "If you are interested in seeing how Black will format your code, you can use the [Black playground](https://black.vercel.app/)" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:102 +msgid "Using a code formatter like Black will leave you more time to work on code function rather than worry about format." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:105 +msgid "Flake8" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:107 +msgid "To adhere to Python `pep8` format standards, you might want to add [flake8](https://flake8.pycqa.org/en/latest/) to your code format toolbox." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:111 +msgid "flake8 will:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:113 +msgid "Flag every line in your code that extends beyond 79 characters (including those in docstrings and comments)" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:114 +msgid "Flag spacing issues that conflict with PEP 8 guidelines such as missing spaces after commas" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:116 +msgid "Flake8 also flags unused imports and unused declared variables in your modules." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:119 +msgid "Below you can see the output of running `flake8 filename.py` at the command line for a Python file within a package called `stravalib`." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:123 +msgid "The line length standard for PEP 8 is 79 characters." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:125 +msgid "Notice that flake8 returns a list of issues that it found in the model.py module on the command line. The Python file itself is not modified. Using this output, you can fix each issue line by line manually." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:140 +msgid "Isort" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:142 +msgid "Python imports refer to the Python packages that a module in your package requires. Imports should always be located at the top of each Python module in your package." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:146 +msgid "[PEP 8 has specific standards for the order of these imports](https://peps.python.org/pep-0008/#imports). These standards are listed below:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:148 +msgid "Imports should be grouped in the following order:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:150 +msgid "Standard library imports." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:151 +msgid "Related third party imports." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:152 +msgid "Local application/library specific imports." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:154 +msgid "While `flake8` will identify unused imports in your code, it won't fix or identify issues with the order of package imports." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:157 +msgid "`isort` will identify where imports in your code are out of order. It will then modify your code, automatically reordering all imports. This leaves you with one less thing to think about when cleaning up your code." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:162 +msgid "Example application of isort" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:164 +msgid "Code imports before `isort` is run:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:166 +msgid "Below, the `pandas` is a third party package, `typing` is a core `Python` package distributed with `Python`, and `examplePy.temperature` is a first-party module which means it belongs to the same package as the file doing the import. Also notice that there are no spaces in the imports listed below." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:176 +msgid "From the project root, run:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:182 +msgid "Python file `temporal.py` imports after `isort` has been run" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:189 +msgid "Ruff" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:191 +msgid "[Ruff](https://docs.astral.sh/ruff/) is a new addition to the code quality ecosystem, gaining some traction since its release. `ruff` is both a linter and a code formatter for Python, aiming to replace several tools behind a single interface. As such, `ruff` can be used at a replacement of all other tools mentioned here, or in complement to some of them." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:197 +msgid "`ruff` has some interesting features that distinguish it from other linters:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:199 +msgid "Linter configuration in `pyproject.toml`" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:200 +msgid "Several hundred rules included, many of which are automatically fixable" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:201 +msgid "Rules explanation, see [F403](https://docs.astral.sh/ruff/rules/undefined-local-with-import-star/) for an example" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:202 +msgid "Fast execution time, makes a quick feedback loop possible even on large projects." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:204 +msgid "Here is a simple configuration to get started with `ruff`. It would go into your `pyproject.toml`:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:212 +msgid "Depending on your project, you might want to add the following to sort imports correctly:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:219 +msgid "How to use code formatter in your local workflow" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:221 +msgid "Linters, code formatters and your favorite coding tools" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:223 +msgid "Linters can be run as a command-line tool as shown above. They also can be run within your favorite coding tool (e.g. VScode, pycharm, etc). For example, you might prefer to have tools like Black and isort run when you save a file. In some editors you can also setup shortcuts that run your favorite code format tools on demand." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:229 +msgid "Use pre-commit hooks to run code formatters and linters on commits" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:231 +msgid "You can also setup a `pre-commit hook` in your Python package repository." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:233 +msgid "A pre-commit hook is a tool that allows an action (or actions) to be triggered when you apply a commit to your git repository." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:236 +msgid "Pre-commit hook example workflow" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:238 +msgid "The precommit workflow looks like this: You type and run:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:241 +msgid "`git commit -m \"message here\"` at the command line" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:243 +msgid "Once you hit return, pre-commit will run any tools that you have configured in a **.pre-commit-config.yaml** file." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:245 +msgid "If the tools configured in the pre-commit hook run successfully without making changes or finding errors in your code, the commit will be applied to the repository." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:249 +msgid "If the tools configured in the hook find errors in your files, the commit will NOT be applied to the repository. Remember from the discussion above that a code formatter like Black will run and reformat your code. A linter like _flake8_ will provide you with some output that details where there are syntax issues in your code. You will then need to fix those issues, manually." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:256 +msgid "Once all of the fixes are applied you can re-add (stage) the files to be commit. And re-run your commit." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:260 +msgid "Diagram showing the steps of a pre-commit workflow from left to right." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:262 +msgid "The pre-commit workflow begins with you adding files that have changes to be staged in git. Next, you'd run git commit. When you run git commit, the pre-commit hooks will then run. In this example, Black, the code formatter and flake8, a linter both run. If all of the files pass Black and flake8 checks, then your commit will be recorded. If they don't, the commit is canceled. You will have to fix any flake8 issues, and then re-add / stage the files to be committed. [_Image Source_](https://ljvmiranda921.github.io/notebook/2018/06/21/precommits-using-black-and-flake8/*)" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:275 +msgid "If have a Python code-base and multiple maintainers actively working on the code, and you intend to run a tool like Black, be sure to coordinate across your team. An initial commit that applies Black to your entire package will likely change a significant amount of your code. This could lead to merge conflicts on open and new PR's before the new changes are merged." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:282 +msgid "General pre commit checks" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:284 +msgid "In addition to calling tools, Pre-commit also has a suite of [built in format hooks](https://github.com/pre-commit/pre-commit-hooks#hooks-available) that you can call. Some, such as `trailing-whitespace` can be also useful to add to your pre-commit workflow to ensure clean, streamlined code files." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:289 +msgid "An example pre-commit-config.yaml file is below with examples of how this is all setup." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:292 +msgid "Pre-commit.ci" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:294 +msgid "[Pre-commit.ci](https://pre-commit.ci) is a bot that may become your new best friend. This bot, when setup on a repo can be configured to do the following:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:297 +msgid "It will check every pull request using all of the pre-commit hook setting" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:298 +msgid "If you wish, it will also submit a pull request to your repo with pre-commit fixes, saving you, and new contributors the time of reformatting a pr that has format issues." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:301 +msgid "You can also call the bot on any pull request to run / and fix the code." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:303 +msgid "The pre-commit.ci bot uses the same pre-commit-config.yaml file that you use to setup pre-commit locally." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:306 +msgid "Setting up a bot like this can be valuable because:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:308 +msgid "It can make is easier for maintainers as they no longer have to worry at allows about fixing code format. The bot will do the work for them." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:310 +msgid "It can make it easier for new comers as they never have to setup pre-commit locally or worry about linting their code. They can even make small fixes to the code directly on GitHub without worry." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:312 +msgid "Setting up a git pre-commit hook" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:314 +msgid "To setup pre-commit locally, you need to do 3 things:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:316 +msgid "Install pre-commit (and include it as a development requirement in your repository)" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:326 +msgid "Create a .pre-commit-config.yaml file in the root of your package directory." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:328 +msgid "Below is an example **.pre-commit-cofig.yaml** file that can be used to setup the pre-commit hook and the pre-commit.ci bot if you chose to implement that too." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:336 +msgid "This file specifies a hook that will be triggered automatically before each `git commit`, in this case, it specifies a `flake8` using version `6.0.0`." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:339 +msgid "Install your pre-commit hook(s) using `pre-commit install`. This will install all of the hooks specified in the pre-commit yaml file into your environment." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:341 +msgid "Once you have done the above, you are ready to start working on your code. Pre-commit will run every time you run `git commit`." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:344 +msgid "Summary" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:346 +msgid "pyOpenSci suggests setting up a linter and a code styler for your package, regardless of whether you use pre-commit hooks, CI or other infrastructure to manage code format. Setting up these tools will give you automatic feedback about your code's structure as you (or a contributor) write it. And using a tool like black that format code for you, reduce effort that you need to make surrounding decisions around code format and style." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:1 +msgid "Complex Python package builds" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:3 +msgid "This guide is focused on packages that are either pure-python or that have a few simple extensions in another language such as C or C++." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:6 +msgid "In the future, we want to provide resources for packaging workflows that require more complex builds. If you have questions about these types of package, please [add a question to our discourse](https://pyopensci.discourse.group/) or open an [issue about this guide specifically in the GitHub repo for this guide](https://github.com/pyOpenSci/python-package-guide/issues). There are many nuances to building and distributing Python packages that have compiled extensions requiring non-Python dependencies at build time. For an overview and thorough discussion of these nuances, please see [this site.](https://pypackaging-native.github.io/)" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:8 +msgid "Pure Python Packages vs. packages with extensions in other languages" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:10 +msgid "You can classify Python package complexity into three general categories. These categories can in turn help you select the correct package frontend and backend tools." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:14 +msgid "**Pure-python packages:** these are packages that only rely on Python to function. Building a pure Python package is simpler. As such, you can chose a tool below that has the features that you want and be done with your decision!" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:16 +msgid "**Python packages with non-Python extensions:** These packages have additional components called extensions written in other languages (such as C or C++). If you have a package with non-Python extensions, then you need to select a build backend tool that allows additional build steps needed to compile your extension code. Further, if you wish to use a frontend tool to support your workflow, you will need to select a tool that supports additional build setups. We suggest that you chose build tool that supports custom build steps like Hatch." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:18 +msgid "**Python packages that have extensions written in different languages (e.g. Fortran and C++) or that have non Python dependencies that are difficult to install (e.g. GDAL):** These packages often have complex build steps (more complex than a package with just a few C extensions for instance). As such, these packages require tools such as [scikit-build](https://scikit-build.readthedocs.io/en/latest/) or [meson-python](https://mesonbuild.com/Python-module.html) to build. NOTE: you can use meson-python with PDM." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:21 +msgid "Mixing frontend and backend projects" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:23 +msgid "It is sometimes necessary or desirable to use a build frontend with an alternative build-backend. This is because some frontends do not have a default backend (`build`), and this choice is placed on the maintainer. Other backends (`hatch`) have a preferred backend (`hatchling`) but allow the maintainer to migrate to another, while some backends (`poetry`) only work with a single backend (`poetry-core`). Refer to (#python-package-build-tools) for more information about frontend and backend compatibility." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:29 +msgid "In this packaging guide we recommend using `hatch` along with its preferred backend `hatchling`. While this will be suitable for most packages, an alternate backend may be used with Hatch if needed when creating an extension module. A Python extension module is one that is made up, either in part or entirely, of compiled code. In this case the backend chosen (such as `meson-python`) must know how to compile the extension language and bind it to Python. `hatchling` does not know how to do this all on its own and must either make use of [plugins](https://hatch.pypa.io/1.9/plugins/about/) or be replaced by a backend that is already capable of building extension modules." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:37 +msgid "In order to use a different backend you will need to edit your project's `pyproject.toml`. If you have a `pyproject.toml` generated by the `hatch` command, or from following the packaging tutorial, you may have to make a change like this" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:8 +#: ../../package-structure-code/declare-dependencies.md:375 +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:22 +msgid "Todo" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:10 +msgid "keep this comment - https://github.com/pyOpenSci/python-package-guide/pull/106#issuecomment-1844278487 in this file for now - jeremiah did a nice inventory of common shells and whether they need quotes or not. It's really comprehensive. But do we want it in the guide?? it's really useful for more advanced users i think." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:12 +msgid "Following this comment: https://github.com/pyOpenSci/python-package-guide/pull/106#pullrequestreview-1766663571" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:15 +msgid "Jonny will add a section that talks about:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:17 +msgid "Why you specify dependencies How to specify dependencies When you use different specifiers" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:22 +msgid "Python Package Dependencies" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:24 +msgid "What is a package dependency?" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:26 +msgid "A Python package dependency refers to an external package or software that your Python project:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:29 +msgid "Needs to function properly." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:30 +msgid "Requires if someone wants to develop / work on improving your package locally or" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:31 +msgid "Requires if a user wants to add additional functionality (that is not core) to your package" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:33 +msgid "A dependency is not part of your project's codebase. It is a package or software that is called within the code of your project or during development of your package." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:37 +msgid "Understanding optional vs. required dependencies" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:38 +msgid "You can think about dependencies as being either optional or required. If they are required, they will be listed in the `dependencies` key in the `project` table of your `pyproject.toml` file. If they are optional, they will be listed in the `[optional.dependencies]` table of your `pyproject.toml`." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:40 +msgid "You will learn about both below." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:46 +msgid "There are two broad groups of Python package dependencies: those that are optional and those that are required. Required packages are those that a user needs to use your package. Optional dependencies are packages a user can chose to install to add functionality to your package. Within those 2 groups, there are three use cases that you can think about. 1. Core dependencies are **required** for a user to use your package. 2. Development dependencies are optional and only needed if someone wants to work on your package locally. 3. Finally feature dependencies are optional and add additional functionality to your package. Not all packages will have feature dependencies." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:51 +msgid "Required (or core) dependencies" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:53 +msgid "Required dependencies are called directly within your package's code. On this page we refer to these dependencies as **core dependencies** as they are needed in order to run your package. You should place your core or required dependencies in the `dependencies` key of the `[project]` table of your `pyproject.toml` file." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:56 +#: ../../package-structure-code/declare-dependencies.md:147 +msgid "Optional dependencies" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:58 +msgid "Optional dependencies dependencies can be optionally installed by users depending upon their needs. There are two broad groups of optional dependencies:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:61 +msgid "**Development dependencies**: These are dependencies that are required to support development of your package. They include tools to run tests such as `pytest`, linters (like `flake8` and `ruff`) and code formatters such as `black` and even automation tools such as `nox` or `tox` that run tasks." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:63 +msgid "**Feature dependencies:** These are dependencies that a user can chose to install to add functionality to your package." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:65 +msgid "When a Python project is installed, the Python package manager (either `pip` or `conda`) installs your package's dependencies automatically. This ensures that when you call a function in a specific dependency, it is available in your user's environment." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:70 +msgid "Dependencies can be added to your pyproject.toml file" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:72 +msgid "In the [pyproject.toml overview page](pyproject-toml-python-package-metadata), you learned how to set up a **pyproject.toml** file with basic metadata for your package. On this page, you will learn how to specify different types of dependencies in your `pyproject.toml`." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:79 +msgid "How do you declare dependencies?" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:81 +msgid "We recommend that you declare your dependencies using your `pyproject.toml` file. This ensures that all of the metadata associated with your package is declared in a single place, making it simpler for users and contributors to understand your package infrastructure." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:86 +msgid "Previously, it was common to use a `requirements.txt` file to declare package dependencies. However in recent years, the ecosystem has moved to storing this information in your **pyproject.toml** file. You may notice however that some projects still maintain a `requirements.txt` file for specific local development needs." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:92 +msgid "Other ways you may see packages storing dependencies" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:95 +msgid "If a project contains extensions written in other languages, you may need a `setup.py` file. Or you may contribute to a package that us using `setup.cfg` for dependency declaration. [Learn more about this in the setuptools documentation](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#declaring-required-dependency)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:100 +msgid "Add required dependencies to your pyproject.toml file" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:102 +msgid "Your core project dependencies need to be installed by a package manager such as `pip` or `conda` when a user installs your package. You can add those dependencies to the `dependencies` array located within the `[project]` table of your **pyproject.toml** file. This looks something like this:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:121 +msgid "Ideally, you should only list the packages that are necessary to install and use your package in the `dependencies` key in the `[project]` table. This minimizes the number of additional packages that your users must install as well as the number of packages that depend upon your package must also install." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:128 +msgid "Remember that fewer dependencies to install reduces the likelihood of version mismatches in user environments." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:131 +msgid "A dependency example" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:133 +msgid "Let's pretend you have a package called `plotMe` that creates beautiful plots of data stored in `numpy` arrays. To create your plots in the `plotMe` package, you use the `seaborn` package to stylize our plots and also `numpy` to process array formatted data." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:135 +msgid "In the example above, the plotMe package, depends upon two packages:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:137 +msgid "seaborn" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:138 +msgid "numpy" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:140 +msgid "This means that in order for plotMe to work in a user's `environment` when installed, you also need to ensure that they have both of those required `dependencies` installed in their environment too." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:142 +msgid "Declaring a dependency in your `pyproject.toml` file will ensure that it is listed as a required dependency when your package is published to PyPI and that a package manager (`pip` or `conda`) will automatically install it into a user's environment alongside your package:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:144 +msgid "`python -m pip install plotMe`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:149 +msgid "Optional dependencies for building your documentation, running your tests and building your package's distribution files are often referred to as development dependencies. These are the dependencies that a user needs to work on your package locally and perform tasks such as:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:151 +msgid "running your test suite" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:152 +msgid "building your documentation" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:153 +msgid "linting and other code cleanup tools" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:155 +msgid "These dependencies are considered optional, because they are not required to install and use your package. Feature dependencies are considered optional and should also be placed in the `[project.optional-dependencies]` table." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:158 +msgid "Optional dependencies can be stored in an `[project.optional-dependencies]` table in your **pyproject.toml** file." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:161 +msgid "It's important to note that within the `[project.optional-dependencies]` table, you can store additional, optional dependencies within named sub-groups. This is a different table than the dependencies array located within the `[project]` table discussed above which contains a single array with a single list of required packages." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:163 +msgid "Create optional dependency groups" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:165 +msgid "To declare optional dependencies in your **pyproject.toml** file:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:167 +msgid "Add a `[project.optional-dependencies]` table to your **pyproject.toml** file." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:168 +msgid "Create named groups of dependencies using the syntax:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:170 +msgid "`group-name = [\"dep1\", \"dep2\"]`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:172 +msgid "Installing packages from GitHub / Gitlab" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:175 +msgid "If you have dependencies that need to be installed directly from GitHub using a `git+https` installation approach, you can do so using the pyproject.toml file like so:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:185 +msgid "IMPORTANT: For security reasons, if your library depends on a GitHub-hosted project, you will need to point to a specific commit/tag/hash of that repository in order to upload your project to PyPI" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:190 +msgid "Below we've created three sets of optional development dependencies named: tests, docs and lint. We've also added a set of feature dependencies." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:213 +msgid "Additional dependency resources" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:215 +msgid "[Learn more: View PyPA's overview of declaring optional dependencies](https://packaging.python.org/en/latest/specifications/declaring-project-metadata/#dependencies-optional-dependencies)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:217 +msgid "[Dependency specifiers](https://packaging.python.org/en/latest/specifications/dependency-specifiers/)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:221 +msgid "Install dependency groups" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:226 +msgid "Diagram showing a Venn diagram with three sections representing the dependency groups listed above - docs feature and tests. In the center it says your-package and lists the core dependencies of that package seaborn and numpy. To the right are two arrows. The first shows the command python - m pip install your-package. It them shows how installing your package that way installs only the package and the two core dependencies into a users environment. Below is a second arrow with python -m pip install youPackage[tests]. This leads to an environment with both the package dependencies - your-package, seaborn and numpy and also the tests dependencies including pytest and pytest-cov" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:228 +msgid "When a user installs your package locally using `python -m pip install your-package` only your package and it's core dependencies get installed. When they install your package `python -m pip install your-package[tests]` pip will install both your package and its core dependencies plus any of the dependencies listed within the tests array of your `[project.optional-dependencies]` table." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:231 +msgid "Using `python -m pip install` vs. `pip install`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:233 +msgid "In all of the examples in this guide, you will notice we are calling `pip` using the syntax:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:236 +msgid "`python -m pip`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:238 +msgid "Calling pip using `python -m` ensures that the `pip` that you are using to install your package comes from your current active Python environment. We strongly suggest that you use this approach whenever you call `pip` to avoid installation conflicts." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:242 +msgid "To ensure this works as you want it to, activate your package's development environment prior to installing anything using `pip`." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:246 +msgid "You can install development dependencies using the groups that you defined above using the syntax:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:249 +msgid "`python -m pip install \".[docs]\"`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:251 +msgid "Above you install:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:252 +msgid "dependencies needed for your documentation (`docs`)," +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:253 +msgid "required package dependencies in the `dependencies` array and" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:254 +msgid "your package" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:256 +msgid "using pip. Below you install your package, required dependencies and optional test dependencies." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:259 +#: ../../package-structure-code/declare-dependencies.md:277 +msgid "`python -m pip install \".[tests]\"`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:261 +msgid "You can install multiple dependency groups in the `[project.optional-dependencies]` table using:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:263 +msgid "`python -m pip install \".[docs, tests, lint]\"`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:266 +msgid "For zsh shell users" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:270 +msgid "There are different shell applications that you and your package contributors might use." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:271 +msgid "zsh is the shell that comes by default on newer Mac OS computers" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:272 +msgid "Windows users may use a tool such as git bash" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:274 +msgid "Some shells don't support unquoted brackets (`[tests]`) which is why we add quotes to the command in this guide like this:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:279 +msgid "In some cases you may see commands without the quotes in guidebooks or contributing guides like the example below:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:282 +msgid "`python -m pip install your-package[tests]`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:284 +msgid "Calling your-package[tests] without the double quotes will work on some shells *but not all*." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:287 +msgid "Combining sets of dependencies" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:289 +msgid "Above we reviewed how to install dependencies from your `pyproject.toml`. In some cases you may want to group sets of dependencies like so:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:302 +msgid "The above allows you to install both the tests and docs dependency lists using the command:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:305 +msgid "`python -m pip install \".[dev]\"`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:308 +msgid "When you install dependencies using the above syntax:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:310 +msgid "`python -m pip install \".[tests, docs]\"`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:312 +msgid "`pip` will also install your package and its core dependencies." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:316 +msgid "Where does conda fit in?" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:319 +msgid "The `pyproject.toml` file allows you to list any Python package published on PyPI (or on GitHub/ GitLab) as a dependency. Once you create this file, declare dependencies, [build your package](python-package-distribution-files-sdist-wheel.md) and [publish your package to PyPI](publish-python-package-pypi-conda.md), people can install both your package and all of it's dependencies with one command." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:322 +msgid "`python -m pip install your-package`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:324 +msgid "This works great if your package is pure-python (no other languages used)." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:326 +msgid "Some packages, particularly in the scientific Python ecosystem, require dependencies that are not written in Python. Conda was created to support distribution of tools that have code written in both Python and languages other than Python." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:329 +msgid "Support conda users with environment.yml files" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:331 +msgid "The above workflow assumes that you want to publish your package on PyPI. And then you plan to publish to conda-forge (optionally), [by submitting a recipe using grayskull](https://www.pyopensci.org/python-package-guide/package-structure-code/publish-python-package-pypi-conda.html)." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:333 +msgid "If you want to support conda users, you may want to also maintain a conda environment that they can use to install your package. Maintaining a conda environment will also help you test that your package installs as you expect into a conda environment." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:336 +msgid "A note for conda users" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:339 +msgid "If you use a conda environment for developing your tool, keep in mind that when you install your package using `python -m pip install -e .` (or using pip in general), dependencies will be installed from PyPI rather than conda." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:341 +msgid "Thus, if you are running a conda environment, installing your package in \"editable\" mode risks dependency conflicts. This is particularly important if you have a spatial package that requires geospatial system libraries like GDAL or another system-level dependency." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:343 +msgid "Alternatively, you can install your package using `python -m pip install -e . --no-deps` to only install the package. And install the rest of your dependencies using a conda environment file." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:346 +msgid "Dependencies in Read the Docs" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:348 +msgid "Now that you have your dependencies specified in your project, you can use them to support other workflows such as publishing to Read the Docs." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:350 +msgid "[Read the Docs](https://readthedocs.org) is a documentation platform with a continuous integration / continuous deployment service that automatically builds and publishes your documentation." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:352 +msgid "If you are using Read the Docs to build your documentation, then you may need to install your dependencies using a **readthedocs.yaml** file." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:354 +msgid "Below is an example of installing the **docs** section of your dependency table in the pyproject.toml file within a readthedocs.yaml file." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:366 +msgid "Read the Docs and Python packages" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:370 +msgid "[Learn more about creating a `readthedocs.yaml` file here. ](https://docs.readthedocs.io/en/stable/config-file/index.html)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:371 +msgid "If you want to install dependencies using Poetry in Read the Docs, [you can learn more here.](https://docs.readthedocs.io/en/stable/build-customization.html#install-dependencies-with-poetry)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:376 +msgid "This is hidden. TO" +msgstr "" + +#: ../../package-structure-code/intro.md:179 +msgid "Intro" +msgstr "" + +#: ../../package-structure-code/intro.md:179 +msgid "Python package structure" +msgstr "" + +#: ../../package-structure-code/intro.md:179 +msgid "pyproject.toml Package Metadata" +msgstr "" + +#: ../../package-structure-code/intro.md:179 +msgid "Build Your Package" +msgstr "" + +#: ../../package-structure-code/intro.md:179 +msgid "Declare dependencies" +msgstr "" + +#: ../../package-structure-code/intro.md:179 +msgid "Package Build Tools" +msgstr "" + +#: ../../package-structure-code/intro.md:179 +msgid "Complex Builds" +msgstr "" + +#: ../../package-structure-code/intro.md:179 +msgid "Create & Build Your Package" +msgstr "" + +#: ../../package-structure-code/intro.md:193 +msgid "Publish with Conda / PyPI" +msgstr "" + +#: ../../package-structure-code/intro.md:193 +msgid "Package versions" +msgstr "" + +#: ../../package-structure-code/intro.md:193 +msgid "Code style" +msgstr "" + +#: ../../package-structure-code/intro.md:193 +msgid "Publish your package" +msgstr "" + +#: ../../package-structure-code/intro.md:1 +msgid "Python Package Structure" +msgstr "" + +#: ../../package-structure-code/intro.md:3 +msgid "This section provides guidance on your Python package's structure, code format, and style. It also reviews the various [packaging tools](python-package-build-tools) you can use to [build](python-package-distribution-files-sdist-wheel) and [publish](publish-python-package-pypi-conda) your Python package." +msgstr "" + +#: ../../package-structure-code/intro.md:7 +msgid "If you want end-to-end tutorials, check out our tutorial series that starts by introducing [what a Python package is](what-is-a-package)." +msgstr "" + +#: ../../package-structure-code/intro.md:9 +msgid "If you are confused by Python packaging, you are not alone! The good news is that some great modern packaging tools ensure you follow best practices. Here, we review tool features and suggest tools you can use for your Python packaging workflow." +msgstr "" + +#: ../../package-structure-code/intro.md:14 +msgid "Checkout our beginning-to-end create a Python package tutorials" +msgstr "" + +#: ../../package-structure-code/intro.md:23 +msgid "How this content is developed" +msgstr "" + +#: ../../package-structure-code/intro.md:24 +msgid "All of the content in this guide has been vetted by community members, including maintainers and developers of the core packaging tools." +msgstr "" + +#: ../../package-structure-code/intro.md:35 +msgid "✨ 1. Package file structure ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:39 +msgid "src layout, flat layout and where should tests folders live? No matter what your level of packaging knowledge is, this page will help you decide upon a package structure that follows modern python best practices." +msgstr "" + +#: ../../package-structure-code/intro.md:44 +msgid "✨ 2. Learn about building your package ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:48 +msgid "To publish your Python package on PyPI, you will need to first build it. The act of \"building\" refers to the process of placing your package code and metadata into a format that can be published on PyPI. Learn more about building your Python package." +msgstr "" + +#: ../../package-structure-code/intro.md:57 +msgid "✨ 4. Add metadata ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:61 +msgid "Learn how to add project metadata to your Python package to support both filtering on PyPI and also the metadata that a package installer needs to build and install your package." +msgstr "" + +#: ../../package-structure-code/intro.md:68 +msgid "✨ 3. What Python package tool should you use? ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:72 +msgid "Learn more about the suite of packaging tools out there. And learn which tool might be best for you." +msgstr "" + +#: ../../package-structure-code/intro.md:78 +msgid "✨ 4. Publish to PyPI and Conda ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:82 +msgid "If you have a pure Python package, it's a straight forward process to publish to both PyPI and then a Conda channel such as conda-forge. Learn more here." +msgstr "" + +#: ../../package-structure-code/intro.md:89 +msgid "✨ 5. Setup package versioning ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:93 +msgid "Semver (numeric versioning) and Calver (versioning using the date) are 2 common ways to version a package. Which one should you pick? Learn more here." +msgstr "" + +#: ../../package-structure-code/intro.md:99 +msgid "✨ 6. Code style & linters ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:103 +msgid "Black, blue, flake8, Ruff - which tools can help you ensure your package follows best practices for code format? Learn more about the options and why this is important here." +msgstr "" + +#: ../../package-structure-code/intro.md:111 +msgid "Figure showing a decision tree with the various packaging tool front-end and back-end options." +msgstr "" + +#: ../../package-structure-code/intro.md:113 +msgid "Diagram showing the various front-end build tools that you can select from. See the packaging tools page to learn more about each tool." +msgstr "" + +#: ../../package-structure-code/intro.md:118 +msgid "If you are considering submitting a package for peer review, have a look at the bare-minimum [editor checks](https://www.pyopensci.org/software-peer-review/how-to/editor-in-chief-guide.html#editor-checklist-template) that pyOpenSci performs before a review begins. These checks are useful to explore for both authors planning to submit a package to us for review and for anyone who is just getting started with creating a Python package." +msgstr "" + +#: ../../package-structure-code/intro.md:125 +msgid "What you will learn here" +msgstr "" + +#: ../../package-structure-code/intro.md:127 +msgid "In this section of our Python packaging guide, we:" +msgstr "" + +#: ../../package-structure-code/intro.md:129 +msgid "Provide an overview of the options available to you when packaging your code." +msgstr "" + +#: ../../package-structure-code/intro.md:131 +msgid "Suggest tools and approaches that both meet your needs and also support existing standards." +msgstr "" + +#: ../../package-structure-code/intro.md:133 +msgid "Suggest tools and approaches that will allow you to expand upon a workflow that may begin as a pure Python code and evolve into code that requires addition layers of complexity in the packaging build." +msgstr "" + +#: ../../package-structure-code/intro.md:136 +msgid "Align our suggestions with the most current, accepted [PEPs (Python Enhancement Protocols)](https://peps.python.org/pep-0000/) and the [Scientific Python community SPECs](https://scientific-python.org/specs/)." +msgstr "" + +#: ../../package-structure-code/intro.md:139 +msgid "In an effort to maintain consistency within our community, we also align with existing best practices being implemented by developers of core Scientific Python packages such as Numpy, SciPy and others." +msgstr "" + +#: ../../package-structure-code/intro.md:143 +msgid "Guidelines for pyOpenSci's packaging recommendations" +msgstr "" + +#: ../../package-structure-code/intro.md:145 +msgid "The flexibility of the Python programming language lends itself to a diverse range of tool options for creating a Python package. Python is so flexible that it is one of the few languages that can be used to wrap around other languages. The ability of Python to wrap other languages is one the reasons you will often hear Python described as a [\"glue\" language](https://numpy.org/doc/stable/user/c-info.python-as-glue.html)\"" +msgstr "" + +#: ../../package-structure-code/intro.md:151 +msgid "If you are building a pure Python package, then your packaging setup can be simple. However, some scientific packages have complex requirements as they may need to support extensions or tools written in other languages such as C or C++." +msgstr "" + +#: ../../package-structure-code/intro.md:155 +msgid "To support the many different uses of Python, there are many ways to create a Python package. In this guide, we suggest packaging approaches and tools based on:" +msgstr "" + +#: ../../package-structure-code/intro.md:158 +msgid "What we think will be best and easiest to adopt for those who are newer to packaging." +msgstr "" + +#: ../../package-structure-code/intro.md:160 +msgid "Tools that we think are well maintained and documented." +msgstr "" + +#: ../../package-structure-code/intro.md:161 +msgid "A shared goal of standardizing packaging approaches across this (scientific) Python ecosystem." +msgstr "" + +#: ../../package-structure-code/intro.md:164 +msgid "Here, we also try to align our suggestions with the most current, accepted [Python community](https://packaging.python.org/en/latest/) and [scientific community](https://scientific-python.org/specs/)." +msgstr "" + +#: ../../package-structure-code/intro.md:167 +msgid "Suggestions in this guide are not pyOpenSci review requirements" +msgstr "" + +#: ../../package-structure-code/intro.md:170 +msgid "The suggestions for package layout in this section are made with the intent of being helpful; they are not specific requirements for your package to be reviewed and accepted into our pyOpenSci open source ecosystem." +msgstr "" + +#: ../../package-structure-code/intro.md:174 +msgid "Please check out our [package scope page](https://www.pyopensci.org/software-peer-review/about/package-scope.html) and [review requirements in our author guide](https://www.pyopensci.org/software-peer-review/how-to/author-guide.html#) if you are looking for pyOpenSci's Python package review requirements!" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:1 +msgid "Publishing Your Package In A Community Repository: PyPI or Anaconda.org" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:5 +msgid "pyOpenSci requires that your package has an distribution that can be installed from a public community repository such as PyPI or a conda channel such as `bioconda` or `conda-forge` on Anaconda.org." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:9 +msgid "Below you will learn more about the various publishing options for your Python package." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:14 +msgid "Installing packages in the same environment using both pip and conda can lead to package conflicts." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:16 +msgid "To minimize conflicts for users who may be using conda (or pip) to manage local environments, consider publishing your package to both PyPI and the conda-forge channel on Anaconda.org." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:18 +msgid "Below you will learn more specifics about the differences between PyPI and conda publishing of your Python package." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:24 +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:6 +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 "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:26 +msgid "Once you have published both package distributions (the source distribution and the wheel) to PyPI, you can then publish to conda-forge. The 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 "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:29 +msgid "What is PyPI" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:31 +msgid "[PyPI](https://pypi.org/) is an online Python package repository that you can use to both find and install and publish your Python package. There is also a test PyPI repository where you can test publishing your package prior to the final publication on PyPI." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:36 +msgid "Many if not most Python packages can be found on PyPI and are thus installable using `pip`." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:38 +msgid "The biggest different between using pip and conda to install a package is that conda can install any package regardless of the language(s) that it is written in. Whereas `pip` can only install Python packages." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:43 +msgid "Click here for a tutorial on publishing your package to PyPI." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:52 +msgid "On the package build page, we discussed the [two package distribution types that you will create when making a Python package](python-package-distribution-files-sdist-wheel): SDist (packaged as a .tar.gz or .zip) and Wheel (.whl) which is really a zip file. Both of those file \"bundles\" will be published on PyPI when you use [a standard build tool](python-package-build-tools) to build your package." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:60 +msgid "What is conda and Anaconda.org?" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:62 +msgid "conda is an open source package and environment management tool. conda can be used to install tools from the [Anaconda repository](https://repo.anaconda.com/)." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:66 +msgid "Anaconda.org contains public and private repositories for packages. These repositories are known as channels (discussed below)." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:69 +msgid "A brief history of conda's evolution" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:72 +msgid "The conda ecosystem evolved years ago to provide support for, and simplify the process of, managing software dependencies in scientific Python projects." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:76 +msgid "Many of the core scientific Python projects depend upon or wrap around tools and extensions that are written in other languages, such as C++. In the early stages of the scientific ecosystem's development, these non-Python extensions and tools were not well supported on PyPI, making publication difficult. In recent years there is more support for complex builds that allow developers to bundle non-Python code into a Python distribution using the [wheel distribution format](python-wheel)." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:78 +msgid "Conda provides a mechanism to manage these dependencies and ensure that the required packages are installed correctly." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:82 +msgid "While conda was originally created to support Python packages, it is now used across all languages. This cross-language support makes it easier for some packages to include and have access to tools written in other languages, such as C/C++ (gdal), Julia, or R. Creating an environment that mixes all of these packages is usually easier and more consistent with full-fledged package managers like conda." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:90 +msgid "conda channels" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:92 +msgid "conda built packages are housed within repositories that are called channels. The conda package manager can install packages from different channels." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:95 +msgid "There are several core public channels that most people use to install packages using conda, including:" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:98 +msgid "**defaults:** this is a channel managed by Anaconda. It is the version of the Python packages that you will install if you install the Anaconda Distribution. Anaconda (the company) decides what packages live on the `defaults` channel." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:99 +msgid "[**conda-forge:**](https://conda-forge.org/) this is a community-driven channel that focuses on scientific packages. This channel is ideal for tools that support geospatial data. Anyone can publish a package to this channel." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:100 +msgid "[**bioconda**](https://bioconda.github.io/): this channel focuses on biomedical tools." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:102 +msgid "**conda-forge** emerged as many of the scientific packages did not exist in the `defaults` Anaconda channel." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:107 +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 "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:109 +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 "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:113 +msgid "conda channels, PyPI, conda, pip - Where to publish your package" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:115 +msgid "You might be wondering why there are different package repositories that can be used to install Python packages." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:118 +msgid "And more importantly you are likely wondering how to pick the right repository to publish your Python package." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:121 +msgid "The answer to both questions relates dependency conflicts." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:125 +msgid "Image showing an XKCD comic that shows a web of Python environments and tools and installations. At the bottom is says - My python environment has become so degraded that my laptop has been declared a superfund site." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:127 +msgid "Installing Python and Python packages from different repositories can lead to environment conflicts where a version of on package doesn't work with a version of another package. To keep your environments clean and working, it's best to install packages from the same repository. So use pip to install everything. Or use conda. If you can, try to avoid installing package from both pip and conda into the same environment." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:135 +msgid "Managing Python package dependency conflicts" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:137 +msgid "Python environments can encounter conflicts because Python tools can be installed from different repositories. Broadly speaking, Python environments have a smaller chance of dependency conflicts when the tools are installed from the same package repository. Thus environments that contain packages installed from both pip and conda are more likely to yield dependency conflicts." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:144 +msgid "Similarly installing packages from the default anaconda channel mixed with the conda-forge channel can also lead to dependency conflicts." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:146 +msgid "Many install packages directly from conda `defaults` channel. However, because this channel is managed by Anaconda, the packages available on it are limited to those that Anaconda decides should be core to a stable installation. The conda-forge channel was created to complement the `defaults` channel. It allows anyone to submit a package to be published in the channel . Thus, `conda-forge` channel ensures that a broad suite of user-developed community packages can be installed from conda." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:150 +msgid "Take-aways: If you can, publish on both PyPI and conda-forge to accommodate more users of your package" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:152 +msgid "The take-away here for maintainers is that if you anticipate users wanting to use conda to manage their local environments (which many do), you should consider publishing to both PyPI and the conda-forge channel (_more on that below_)." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:157 +msgid "Additional resources" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:158 +msgid "[learn more about why conda-forge was created, here](https://conda-forge.org/docs/user/introduction.html)" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:160 +msgid "[To learn more about conda terminology, check out their glossary.](https://docs.conda.io/projects/conda/en/latest/glossary.html )" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:165 +msgid "How to submit to conda-forge" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:167 +msgid "While pyOpenSci doesn't require you to add your package to conda-forge, we encourage you to consider doing so!" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:170 +msgid "Once your package is on PyPI, the process to add your package to conda-forge is straight forward to do. [You can follow the detailed steps provided by the conda-forge maintainer team.](https://conda-forge.org/docs/maintainer/adding_pkgs.html)." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:175 +msgid "Click here for a tutorial on adding your package to conda-forge." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:182 +msgid "If you want a step by step tutorial, click here." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:185 +msgid "Once your package is added, you will have a feedstock repository on GitHub with your packages name" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:188 +msgid "[Here is an example conda-forge feedstock for the pyOpenSci approved package - movingpandas](https://github.com/conda-forge/movingpandas-feedstock)" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:191 +msgid "Maintaining your conda-forge package repository" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:193 +msgid "Once your package is on the conda-forge channel, maintaining it is simple. Every time that you push a new version of your package to PyPI, it will kick off a continuous integration build that updates your package in the conda-forge repository. Once that build is complete, you will get a notification to review the update." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:199 +msgid "You can merge the pull request for that update once you are happy with it. A ready-to-merge PR usually means ensuring that your project's dependencies (known as runtime requirements) listed in the updated YAML file found in the pull request match the PyPI metadata of the new release." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:1 +msgid "Use a pyproject.toml file for your package configuration & metadata" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:10 +msgid "Important pyproject.toml take aways" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:14 +msgid "There are only two tables that are required for an installable Python package: **[build-system]** and **[project]**. The **[project]** table stores your package's metadata." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:15 +msgid "There are only two _required_ fields in the **[project]** table: **name=** and **version=**." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:16 +msgid "We suggest you add additional metadata to your `pyproject.toml` file as it will make it easier for users to find your project on PyPI." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:17 +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 your package or publish to PyPI." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:18 +msgid "There is no specific order for tables in the `pyproject.toml` file. However fields need to be placed within the correct table sections. For example `requires =` always need to be associated with the **[build-system]** table." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:19 +msgid "**python-requires**: is important to have in your `pyproject.toml` file as it helps pip install your package." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:24 +msgid "when these are published, remove this todo" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:33 +msgid "Need help creating your pyproject.toml file? This tutorial will walk you through the process." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:47 +msgid "Click here if need help migrating from setup.py/setup.cfg to pyproject.toml" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:57 +msgid "About the pyproject.toml file" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:59 +msgid "Every modern Python package should include a `pyproject.toml` file. If your project is pure Python and you're using a `setup.py` or `setup.cfg` file to describe its metadata, you should consider migrating your metadata and build information to a `pyproject.toml` file." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:61 +msgid "If your project isn’t pure-python, you might still require a `setup.py` file to build the non Python extensions. However, a `pyproject.toml` file should still be used to store your project’s metadata." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:63 +msgid "What happened to setup.py & how do i migrate to pyproject.toml?" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:65 +msgid "Prior to August 2017, Python package metadata was stored either in the `setup.py` file or a `setup.cfg` file. In recent years, there has been a shift to storing Python package metadata in a much more user-readable `pyproject.toml` format. Having all metadata in a single file:" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:67 +msgid "simplifies package management," +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:68 +msgid "allows you to use a suite of different [build backends](https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-build-tools.html#build-back-ends) such as (flit-core, hatchling, pdm-build), and" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:69 +msgid "aligns with modern best practices." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:76 +msgid "The standard file that Python packages use to [specify build requirements and metadata is called a **pyproject.toml**](https://packaging.python.org/en/latest/specifications/declaring-project-metadata/). Adding metadata, build requirements and package dependencies to a **pyproject.toml** file replaces storing that information in a setup.py or setup.cfg file." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:81 +msgid "About the .toml format" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:83 +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 founded on key/value pairs. Each section in the **pyproject.toml** file contains a `[table identifier]`. Below that table identifier are key/value pairs that support configuration for that particular table." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:87 +msgid "Below `[build-system]` is considered a table in the toml language." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:88 +msgid "Within the `build-system` table below `requires =` is a key." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:89 +msgid "The associated value for `requires` is an array containing the value `\"hatchling\"`." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:97 +msgid "How the pyproject.toml is used when you build a package" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:101 +msgid "When you publish to PyPI, you will notice that each package has metadata listed. Let’s have a look at [xclim](https://pypi.org/project/xclim/), one of our [pyOpenSci packages](https://www.pyopensci.org/python-packages.html). Notice that on the PyPI landing page you see some metadata about the package including python, maintainer information and more. PyPI is able to populate this metadata because it was defined using correct syntax and classifiers by Xclim's maintainers, [pyproject.toml file](https://github.com/Ouranosinc/xclim/blob/master/pyproject.toml). This metadata when the xclim package is built, is translated into a distribution file that allows PyPI to read the metadata and print it out on their website." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:103 +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:83 +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 "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:108 +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:88 +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 "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:113 +msgid "Benefits of using a pyproject.toml file" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:115 +msgid "Including your package's metadata in a separate human-readable **pyproject.toml** format also allows someone to view the project's metadata in a GitHub repository." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:123 +msgid "Setup.py is still useful for complex package builds" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:127 +msgid "Using **setup.py** to manage package builds and metadata [can cause problems with package development](https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html). In some cases where a Python package build is complex, a **setup.py** file may be required. While this guide will not cover complex builds, we will provide resources working with complex builds in the future." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:133 +msgid "Optional vs. Required pyproject.toml file fields" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:135 +msgid "When you create your `pyproject.toml` file, there are numerous metadata fields that you can use. Below we suggest specific fields to get you started that support publication on PyPI and users finding your package." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:137 +msgid "[An overview of all of the project metadata elements can be found here.](https://packaging.python.org/en/latest/specifications/core-metadata/#project-url-multiple-use)" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:139 +msgid "Required fields for the `[project]` table" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:141 +msgid "As mentioned above, your `pyproject.toml` file needs to have a **`name`** and **`version`** field in order to properly build your package:" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:143 +msgid "`name`: This is the name of your project provided as a string" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:144 +msgid "`version`: This is the version of your project. If you are using a SCM tool for versioning (using git tags to determine versions), then the version may be dynamic (more on that below)." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:146 +msgid "Optional fields to include in the `[project]` table" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:148 +msgid "We strongly suggest that you also add the metadata keys below as they will help users finding your package on PyPI. These fields will make it clear how your package is structured, what platforms you support and what dependencies your package requires." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:153 +msgid "**Description:** this is a short one-line description of your package." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:154 +msgid "**Readme:** A link to your README.md file is used for the long long-description. This information will be published on your packages PyPI landing page." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:155 +msgid "**Requires-python** (used by pip): this is a field that is used by pip. Here you tell the installer whether you are using Python 2.x or 3.x. Most projects will be using 3.x." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:156 +msgid "**License:** the license you are using" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:157 +msgid "**Authors:** these are the original authors of the package. Sometimes the authors are different from the maintainers. Other times they might be the same." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:158 +msgid "**Maintainers:** you can choose to populate this or not. You can populate this using a list with a sub element for each author or maintainer name, email" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:166 +msgid "**dependencies:** dependencies are optional but we strongly suggest you include them in your pyproject.toml. Dependencies will be installed by pip when your project is installed creating a better user-experience." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:168 +msgid "**`[project.optional-dependencies]`:** the optional or development dependencies will be installed if someone runs `python -m pip install projectname[dev]`. This is a nice way to include your development dependencies for users who may wish to contribute to your project." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:170 +msgid "**keywords:** These are the keywords that will appear on your PyPI landing page. Think of them as words that people might use to search for your package." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:171 +msgid "**classifiers:** The classifiers section of your metadata is also important for the landing page of your package in PyPI and for filtering of packages in PyPI. A list of [all options for classifiers can be found her](https://PyPI.org/classifiers/)e. Some of the classifiers that you should consider including" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:172 +msgid "Development Status" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:173 +msgid "Intended Audience" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:174 +msgid "Topic" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:175 +msgid "License" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:176 +msgid "Programming language" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:178 +msgid "Advanced options in the pyproject.toml file" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:180 +msgid "The examples at the bottom of this page contain ..." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:182 +msgid "**`[project.scripts]` (Entry points):** Entry points are optional. If you have a command line tool that runs a specific script hosted in your package, you may include an entry point to call that script directly at the command line (rather than at the Python shell)." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:184 +msgid "Here is an example of[a package that has entry point script](https://github.com/pyOpenSci/pyosMeta/blob/main/pyproject.toml#L60)s. Notice that there are several core scripts defined in that package that perform sets of tasks. The pyOpenSci is using those scripts to process their metadata." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:185 +msgid "**Dynamic Fields:** if you have fields that are dynamically populated. One example of this is if you are using scm / version control based version with tools like `setuptooms_scm`, then you might use the dynamic field, such as version (using scm) **dynamic = [\"version\"]**" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:187 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Add dependencies to your pyproject.toml file" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:189 +msgid "The pyproject.toml file can also be used as a replacement for the requirements.txt file which has been traditionally used to store development dependencies such as pytest, code formatters such as Black and documentation tools such as sphinx." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:191 +msgid "To add dependencies to your build, add a `[project.optional-dependencies]` table to your pyproject.toml file." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:193 +msgid "Then specify dependency groups as follows:" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:200 +msgid "Following the above example, you install dependencies like this:" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:202 +msgid "`python -m pip install -e .[tests]`" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:204 +msgid "The above will install both your package in editable mode and all of the dependencies declared in the tests section of your `[project.optional-dependencies]` table." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:206 +msgid "To install all dependencies and also your package, you'd use:" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:208 +msgid "`python -m pip install -e .[tests,lint,docs]`" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:210 +msgid "Recursive dependencies" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:214 +msgid "You can also setup sets of recursive dependencies. [See this blog post for more.](https://hynek.me/articles/python-recursive-optional-dependencies/)" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:217 +msgid "Example pyproject.toml for building using hatchling" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:219 +msgid "Below is an example build configuration for a Python project. This example package setup uses **hatchling** to build the [package's sdist and wheels](python-package-distribution-files-sdist-wheel)." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:227 +msgid "Notice that dependencies are specified in this file." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:229 +msgid "Example pyproject.toml for building using setuptools" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:231 +msgid "The package metadata including authors, keywords, etc is also easy to read. Below you can see the same TOML file that uses a different build system (setuptools). Notice how simple it is to swap out the tools needed to build this package!" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:235 +msgid "In this example package setup you use:" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:237 +msgid "**setuptools** to build the [package's sdist and wheels](python-package-distribution-files-sdist-wheel)" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:238 +msgid "**setuptools_scm** to manage package version updates using version control tags" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:240 +msgid "In the example below `[build-system]` is the first table of values. It has two keys that specify the build backend API and containing package:" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:243 +msgid "`requires =`" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:244 +msgid "`build-back-end =`" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:251 +msgid "[Click here to read about our packaging build tools including PDM, setuptools, Poetry and Hatch.](/package-structure-code/python-package-build-tools)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:1 +msgid "Python Packaging Tools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:3 +msgid "Tools for building your package" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:5 +msgid "There are a several different build tools that you can use to [create your Python package's _sdist_ and _wheel_ distributions](python-package-distribution-files-sdist-wheel). Below, we discuss the features, benefits and limitations of the most commonly used Python packaging tools. We focus on pure-python packages in this guide. However, we also highlight tools that currently support packages with C/C++ and other language extensions." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:13 +msgid "Decision tree diagram showing the various front and back end packaging tools. You can decide what packaging tool to use by thinking about what features you need. PDM and Hatch are currently the most flexible tools as they also using different build back-ends. As such currently PDM and Hatch are the tools we think beginners might appreciate most with Poetry being a close second. Poetry is nice for pure Python projects." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:15 +msgid "Diagram showing the different front end build tools available to use in the Python package ecosystem that you can select from. We selected tools to include in this diagram based upon the PyPI survey which helped us understand the most populate tools in the ecosystem. Each tool has different features as highlighted below." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:18 +msgid "If you want to know more about Python packages that have extensions written in other languages, [check out the page on complex package builds.](complex-python-package-builds)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:21 +msgid "Tools that we review here" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:23 +msgid "In this section we have selected tools that were returned as the most popular packaging tools in the PyPA survey. You will learn more about the following tools on this page:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:27 +msgid "[Twine](https://twine.readthedocs.io/en/stable/), [Build](https://pypa-build.readthedocs.io/en/stable/) + [setuptools](https://setuptools.pypa.io/en/latest/)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:28 +msgid "[Flit](https://flit.pypa.io/en/stable/)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:29 +msgid "[Hatch](https://hatch.pypa.io/latest/)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:30 +msgid "[PDM](https://pdm.fming.dev/latest/)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:31 +msgid "[Poetry](https://python-poetry.org/docs/)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:33 +msgid "Summary of tools Hatch vs. PDM vs. Poetry (and setuptools)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:35 +msgid "If you are looking for a quick summary, read below." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:37 +msgid "In general, any modern tool that you select from this page will be great to build your package. Selecting a tool comes down to the features that you are looking for in your workflow." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:38 +msgid "We suggest that beginners start with a modern workflow tool like PDM as opposed to navigating the complexities of setuptools." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:39 +msgid "If you are going to use Poetry (it is the most popular tool and does have the best documentation) beware of the upper bounds dependency additions and consider overriding dependencies when you add them. If you do that Poetry will work well for pure-python builds! Poetry also has an active discord where you can ask questions." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:41 +msgid "Below are some features that Hatch and PDM offer that Poetry does not." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:43 +msgid "PDM:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:45 +msgid "Supports other back-ends making it ideal for builds that are not pure Python. This means PDM is a great option for both pure python and more complex Python builds as it supports meson-python and other build backends." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:46 +msgid "Offers flexibility in dependency management which we like" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:47 +msgid "Offers lock files if you need them" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:49 +msgid "Hatch:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:51 +msgid "Offers matrix environment management that allows you to run tests across Python versions. If this feature is important to you, then Hatch is a clear winner." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:52 +msgid "Offers a Nox / Make file like tool to streamline your build workflow. If you are looking to reduce the number of tools in your workflow, Hatch might be for you." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:55 +msgid "Build front-end vs. build back-end tools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:57 +msgid "To better understand your options, when it comes to building a Python package, it's important to first understand the difference between a build tool front-end and build back-end." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:62 +msgid "Build back-ends" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:64 +msgid "Most packaging tools have a back-end build tool that builds you package and creates associated [(sdist and wheel) distribution files](python-package-distribution-files-sdist-wheel). Some tools, such as **Flit**, only support pure-Python package builds. A pure-Python build refers to a package build that does not have extensions that are written in another programming language (such as `C` or `C++`)." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:71 +msgid "Other packages that have C and C++ extensions (or that wrap other languages such as fortran) require additional code compilation steps when built. Back-ends such as **setuptools.build**, **meson.build** and **scikit-build** support complex builds with custom steps. If your build is particularly complex (i.e. you have more than a few `C`/`C++` extensions), then we suggest you use **meson.build** or **scikit-build**." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:77 +msgid "Python package build front-ends" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:79 +msgid "A packaging front-end tool refers to a tool that makes it easier for you to perform common packaging tasks using similar commands. These tasks include:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:82 +msgid "[Build your packages (create the sdist and wheel distributions)](python-package-distribution-files-sdist-wheel)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:83 +msgid "Installing your package in a development mode (so it updates when you update your code)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:84 +msgid "Publishing to PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:85 +msgid "Running tests" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:86 +msgid "Building documentation" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:87 +msgid "Managing an environment or multiple environments in which you need to run tests and develop your package" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:89 +msgid "There are several Python packaging tools that you can use for pure Python builds. Each front-end tool discussed below supports a slightly different set of Python packaging tasks." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:93 +msgid "For instance, you can use the packaging tools **Flit**, **Hatch** or **PDM** to both build and publish your package to PyPI. However while **Hatch** and **PDM** support versioning and environment management, **Flit** does not. If you want a tool that supports dependency locking, you can use **PDM** or **Poetry** but not **Hatch**. If you only need to build your package's sdist and wheel distribution files, then you can stick with PyPA's Build. You'd then use Twine to publish to PyPI." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:100 +msgid "If you are using **Setuptools**, there is no default user-friendly build front-end that performs multiple tasks. You will need to use **build** to build your package and **twine** to publish to PyPI." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:103 +msgid "Example build steps that can be simplified using a front-end tool" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:105 +msgid "Below, you can see how a build tool streamlines your packaging experience. Example to build your package with **Hatch**:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:115 +msgid "Example build steps using the **setuptools** back-end and **build**:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:125 +msgid "Choosing a build back-end" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:127 +msgid "Most front-end packaging tools have their own back-end build tool. The build tool creates your package's (sdist and wheel) distribution files. For pure Python packages, the main difference between the different build back-ends discussed below is:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:132 +msgid "How configurable they are - for example, do they allow you to add build steps that support non python extensions?" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:133 +msgid "How much you need to configure them to ensure the correct files are included in your sdist and wheel distributions." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:135 +msgid "Build back-end support for non pure-python packages" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:137 +msgid "It is important to note that some build back-ends, such as **Flit-core**, only support pure Python builds. Other back-ends support C and C++ extensions as follows:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:140 +msgid "setuptools supports builds using C / C++ extensions" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:141 +msgid "Hatchling (hatch's back-end) supports C / C++ extensions via plugins that the developer creates to customize a build" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:142 +msgid "PDM's back-end supports C / C++ extensions by using setuptools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:143 +msgid "Poetry's back-end supports C/C++ extensions however this functionality is currently undocumented. As such we don't recommend using Poetry for complex or non pure Python builds until it is documented." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:145 +msgid "While we won't discuss more complex builds below, we will identify which tools have documented support for C / C++ extensions." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:148 +msgid "An ecosystem of Python build tools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:150 +msgid "Below we introduce several of the most commonly used Python packaging build front-end tools. We highlight the features that each tool offers as a way to help you decide what tool might be best for your workflow." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:154 +msgid "We do not suggest using setuptools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:157 +msgid "We suggest that you pick one of the modern tools listed above rather than setuptools because setuptools will require some additional knowledge to set up correctly." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:161 +msgid "We review setuptools as a back-end because it is still popular. However it is not the most user friendly option." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:165 +msgid "The most commonly used tools in the ecosystem are setuptools back-end (with build) and Poetry (a front end tool with numerous features and excellent documentation)." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:171 +msgid "Graph showing the results of the 2022 PyPA survey of Python packaging tools. On the x axis is percent response and on the y axis are the tools." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:173 +msgid "The Python developers survey results (n=>8,000 PyPI users) show setuptools and poetry as the most commonly used Python packaging tools. The core tools that we've seen being used in the scientific community are included here. [You can view the full survey results by clicking here.](https://drive.google.com/file/d/1U5d5SiXLVkzDpS0i1dJIA4Hu5Qg704T9/view) NOTE: this data represent maintainers across domains and is likely heavily represented by those in web development. So this represents a snapshot across the broader Python ecosystem." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:176 +msgid "Chose a build workflow tool" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:178 +msgid "The tools that we review below include:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:180 +msgid "Twine, Build + setuptools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:181 +#: ../../package-structure-code/python-package-build-tools.md:291 +msgid "Flit" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:182 +#: ../../package-structure-code/python-package-build-tools.md:331 +msgid "Hatch" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:183 +#: ../../package-structure-code/python-package-build-tools.md:215 +#: ../../package-structure-code/python-package-build-tools.md:230 +msgid "PDM" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:184 +#: ../../package-structure-code/python-package-build-tools.md:374 +msgid "Poetry" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:186 +msgid "When you are selecting a tool, you might consider this general workflow of questions:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:189 +msgid "**Is your tool pure python? Yes?** You can use any tool that you wish! Pick the tool that has the features that you want to use in your build workflow. We suggest:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:191 +msgid "Flit, Hatch, PDM or Poetry (read below for more)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:193 +msgid "**Does your tool have a few C or C++ extensions?** Great, we suggest using **PDM** for the time being. It is the only tool in the list below that has both documented workflow to support such extensions and support for other back-ends in the case that build hooks are not enough for your workflow. PDM supports other back-ends such as scikit-build and meson-python that will allow you to fully customize your package's build." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:197 +msgid "NOTE: You can also use Hatch for non pure python builds. Hatch, similar to PDM, allows you to write your own build hooks or plugins to support custom build steps. But currently, hatch does not support other build back ends. Many of the core scientific packages are moving to meson-python to build their packages. Thus, we appreciate that PDM can work with meson-python specifically." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:199 +msgid "Python packaging tools summary" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:201 +msgid "Below, we summarize features offered by the most popular build front end tools. It is important to keep in mind that these front-end tools remove the need to use other core tools in your workflow. For example if you use setuptools, you will need to also use Build and Twine to build your package and publish to PyPI. But if you use Poetry, Hatch or PDM you can do all of those things using the same tool (e.g. `hatch build`, `hatch publish` or `pdm build`, `pdm publish`)." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:204 +msgid "Note that because setuptools does not offer a front-end interface, it is not included in the table." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:208 +msgid "Package tool features table" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +msgid "Feature, Flit, Hatch, PDM, Poetry" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +msgid "Default Build Back-end" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +msgid "Flit-core" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +msgid "hatchling" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +msgid "Poetry-core" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +#: ../../package-structure-code/python-package-build-tools.md:251 +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Use Other Build Backends" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "✖" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +#: ../../package-structure-code/python-package-build-tools.md:251 +#: ../../package-structure-code/python-package-build-tools.md:304 +#: ../../package-structure-code/python-package-build-tools.md:348 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "✅" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Dependency management" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "Publish to PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +msgid "Version Control based versioning (using `git tags`)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +#: ../../package-structure-code/python-package-build-tools.md:251 +#: ../../package-structure-code/python-package-build-tools.md:348 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Version bumping" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Environment Management" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +msgid "More than one maintainer? (bus factor)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:225 +msgid "Notes:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:227 +msgid "_Hatch plans to support dependency management in the future_" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:228 +msgid "Poetry supports semantic versioning. Thus, it will support version bumping following commit messages if you use a tool such as Python Semantic Release" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:232 +msgid "[PDM is a Python packaging and dependency management tool](https://pdm.fming.dev/latest/). PDM supports builds for pure Python projects. It also provides multiple layers of support for projects that have C and C++ extensions." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:236 +msgid "PDM support for C and C++ extensions" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:238 +msgid "PDM supports using the PDM-back-end and setuptools at the same time. This means that you can run setuptools to compile and build C extensions. PDM's build back-end receives the compiled extension files (.so, .pyd) and packages them with the pure Python files." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:244 +msgid "PDM Features" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "Feature, PDM, Notes" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "When you setup PDM it allows you to select one of several build back ends including: PDM-core, flit-core and hatchling. PDM also can work with Meson-Python which supports move complex python builds." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "Dependency specifications" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "PDM has flexible support for managing dependencies. PDM defaults to using an open bound (e.g. `requests >=1.2`) approach to dependencies. However you can [customize how you want to add dependencies in case you prefer another approach such as that of Poetry which uses an upper bound limit](https://pdm.fming.dev/latest/usage/dependency/#about-update-strategy).**" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "Environment lock files" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "PDM and Poetry are currently the only tools that create environment lock files. Lock files are often most useful to developers creating web apps where locking the environment is critical for consistent user experience. For community-used packages, you will likely never want to use a lock file." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Environment management" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "PDM provides environment management support. It supports Python virtual environments, conda and a local `__pypackages__` environment which is a newer option in the Python ecosystem. No extensions are needed for this support." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "Select your environment type on install" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "When you run `PDM init`, PDM will discover environments that are already on your system and allow you to select one to use for your project." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "PDM supports publishing to both test PyPI and PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +#: ../../package-structure-code/python-package-build-tools.md:348 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Version Control based versioning" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "PDM has a setuptools_scm like tool built into it which allows you to use dynamic versioning that rely on git tags." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "PDM supports you bumping the version of your package using standard semantic version terms patch; minor; major" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +#: ../../package-structure-code/python-package-build-tools.md:304 +#: ../../package-structure-code/python-package-build-tools.md:348 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Follows current packaging standards" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "PDM supports current packaging standards for adding metadata to the **pyproject.toml** file." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +#: ../../package-structure-code/python-package-build-tools.md:304 +#: ../../package-structure-code/python-package-build-tools.md:348 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Install your package in editable mode" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "PDM supports installing your package in editable mode." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +#: ../../package-structure-code/python-package-build-tools.md:304 +#: ../../package-structure-code/python-package-build-tools.md:348 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Build your sdist and wheel distributions" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "Similar to all of the other tools PDM builds your packages sdist and wheel files for you." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:264 +msgid "PDM vs. Poetry" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:265 +msgid "The functionality of PDM is similar to Poetry. However, PDM also offers additional, documented support for C extensions and version control based versioning. As such, PDM is preferred for those working on non pure-Python packages." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:269 +msgid "If you are deciding between the Poetry and PDM, a smaller difference is the default way that dependencies are added to your pyproject.toml file." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:271 +msgid "Poetry by default follows strict semantic versioning adding dependencies to your pyproject.toml file [using an upper bounds constraint (`^`)](https://python-poetry.org/docs/dependency-specification/#version-constraints). Upper bounds lock means that Poetry will never bump a dependency to the next major version (i.e. from 1.2 to 2.0). However, you can tell Poetry to use an open bound approach by explicitly adding the package like this: `poetry add requests >= 1.2` rather than just using `poetry add requests` which will result in a upper bound locked (ie Upper bound locks means that requests 2.0 could never be installed even if it came out and your package could benefit from it)." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:272 +msgid "PDM defaults to open-bounds (`>=`) dependency additions which is the preferred approach in the scientific python ecosystem. However, PDM also allows you to specify the way dependencies are added by default. As such, you can also specify upper-bounds (`^`) using PDM if require that approach." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:274 +msgid "Finally there are some nuanced differences in how both tools create lock files which we will not go into detail about here." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:277 +msgid "Challenges with PDM" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:279 +msgid "PDM is a full-featured packaging tool. However it is not without challenges:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:281 +msgid "Its documentation can be confusing, especially if you are new to packaging. For example, PDM doesn't provide an end to end beginning workflow in its documentation." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:283 +msgid "PDM also only has one maintainer currently. We consider individual maintainer teams to be a potential risk. If the maintainer finds they no longer have time to work on the project, it leaves users with a gap in support. Hatch and Flit also have single maintainer teams." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:288 +msgid "[You can view an example of a package that uses PDM here](https://github.com/pyOpenSci/examplePy/tree/main/example4_pdm). The README file for this directly provides you with an overview of what the PDM command line interface looks like when you use it." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:293 +msgid "[Flit is a no-frills, streamlined packaging tool](https://flit.pypa.io/en/stable/) that supports modern Python packaging standards. Flit is a great choice if you are building a basic package to use in a local workflow that doesn't require any advanced features. And if your package structure is already created. More on that below." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:297 +msgid "Flit Features" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:304 +msgid "Feature, Flit, Notes" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:304 +#: ../../package-structure-code/python-package-build-tools.md:348 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Publish to PyPI and test PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:304 +msgid "Flit supports publishing to both test PyPI and PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:304 +msgid "Helps you add metadata to your **pyproject.toml** file" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:304 +msgid "Flit does support adding metadata to your **pyproject.toml** file following modern packaging standards." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:304 +msgid "Flit supports current packaging standards for adding metadata to the **pyproject.toml** file." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:304 +msgid "Flit supports installing your package in editable mode.**" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:304 +msgid "Flit can be used to build your packages sdist and wheel distributions." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:311 +msgid "NOTE: _If you are using the most current version of pip, it supports both a symlink approach `flit install -s` and `python -m pip install -e .`_" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:313 +msgid "Learn more about flit" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:314 +msgid "[Why use flit?](https://flit.pypa.io/en/stable/rationale.html)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:317 +msgid "Why you might not want to use Flit" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:319 +msgid "Because Flit is no frills, it is best for basic, quick builds. If you are a beginner you may want to select Hatch or PDM which will offer you more support in common operations." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:323 +msgid "You may NOT want to use flit if:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:325 +msgid "You want to setup more advanced version tracking and management (using version control for version bumping)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:326 +msgid "You want a tool that handles dependency versions (use PDM or Poetry instead)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:327 +msgid "You have a project that is not pure Python (Use Hatch, PDM or setuptools)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:328 +msgid "You want environment management (use PDM, Hatch or Poetry)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:333 +msgid "[**Hatch**](https://hatch.pypa.io/latest/), similar to Poetry and PDM, provides a unified command line interface. To separate Hatch from Poetry and PDM, it also provides an environment manager for testing that will make it easier for you to run tests locally across different versions of Python. It also offers a nox / makefile like feature that allows you to create custom build workflows such as building your documentation locally. This means that you could potentially drop a tool like **Make** or **Nox** from your workflow and use Hatch instead." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:340 +msgid "Hatch features" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Feature, Hatch, Notes" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Hatch is used with the backend Hatchling by default, but allows you to use another backend by switching the declaration in pyproject.toml." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Currently you have to add dependencies manually with Hatch. However a feature to support dependencies management may be added in a future release." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Hatch supports Python virtual environments. If you wish to use other types of environments such as Conda, you will need to [install a plugin such as hatch-conda for conda support](https://github.com/OldGrumpyViking/hatch-conda)." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Hatch supports publishing to both test PyPI and PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Hatch offers `hatch_vcs` which is a plugin that uses setuptools_scm to support versioning using git tags. The workflow with `hatch_vcs` is the same as that with `setuptools_scm`." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Hatch supports you bumping the version of your package using standard semantic version terms patch; minor; major" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Hatch supports current packaging standards for adding metadata to the **pyproject.toml** file." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Hatch will install your package into any of its environments by default in editable mode. You can install your package in editable mode manually using `python -m pip install -e .` Hatch mentions [editable installs](https://hatch.pypa.io/latest/config/build/#dev-mode) but refers to pip in its documentation." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Hatch will build the sdist and wheel distributions" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "✨Matrix environment creation to support testing across Python versions✨" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "The matrix environment creation is a feature that is unique to Hatch in the packaging ecosystem. This feature is useful if you wish to test your package locally across Python versions (instead of using a tool such as tox)." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "✨[Nox / MAKEFILE like functionality](https://hatch.pypa.io/latest/environment/#selection)✨" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "This feature is also unique to Hatch. This functionality allows you to create workflows in the **pyproject.toml** configuration to do things like serve docs locally and clean your package build directory. This means you may have one less tool in your build workflow." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "✨A flexible build backend: **hatchling**✨" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "**The hatchling build backend offered by the maintainer of Hatch allows developers to easily build plugins to support custom build steps when packaging." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:362 +msgid "_There is some argument about this approach placing a burden on maintainers to create a custom build system. But others appreciate the flexibility. The Hatch build hook approach is also comparable with the features offered by PDM._" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:364 +msgid "Why you might not want to use Hatch" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:366 +msgid "There are a few features that hatch is missing that may be important for some. These include:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:369 +msgid "Hatch doesn't support adding dependencies. You will have to add them manually." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:370 +msgid "Hatch won't by default recognize Conda environments without a plugin." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:371 +msgid "Similar to PDM, Hatch's documentation can difficult to work through, particularly if you are just getting started with creating a package." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:372 +msgid "Hatch, similar to PDM and Flit currently only has one maintainer." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:376 +msgid "[Poetry is a full-featured build tool.](https://python-poetry.org/) It is also the second most popular front-end packaging tool (based upon the PyPA survey). Poetry is user-friendly and has clean and easy-to-read documentation." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:381 +msgid "While some have used Poetry for Python builds with C/C++ extensions, this support is currently undocumented. Thus, we don't recommend using Poetry for more complex builds." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:385 +msgid "Poetry features" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Feature, Poetry, Notes" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Poetry helps you add dependencies to your `pyproject.toml` metadata. _NOTE: currently Poetry adds dependencies using an approach that is slightly out of alignment with current Python peps - however there is a plan to fix this in an upcoming release._ Poetry also allows you to organize dependencies in groups such as documentation, packaging and tests." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Dependency specification" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Poetry allows you to be specific about version of dependencies that you add to your package's pyproject.toml file. However, it's default upper bound approach can be problematic for some packages (We suggest you override the default setting when adding dependencies). Read below for more." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Poetry allows you to either use its built in environment or you can select the environment type that you want to use for managing your package. [Read more about its built in environment management options](https://python-poetry.org/docs/basic-usage/#using-your-virtual-environment)." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Lock files" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Poetry creates a **poetry.lock** file that you can use if you need a lock file for your build." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Poetry supports publishing to both test PyPI and PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "The plugin [Poetry dynamic versioning](https://github.com/mtkennerly/poetry-dynamic-versioning) supports versioning using git tags with Poetry." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Poetry supports you bumping the version of your package using standard semantic version terms patch; minor; major" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "✖✅" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Poetry does not quite support current packaging standards for adding metadata to the **pyproject.toml** file but plans to fix this in an upcoming release." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Poetry supports installing your package in editable mode using `--editable`" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Poetry will build your sdist and wheel distributions using `poetry build`" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:407 +msgid "Challenges with Poetry" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:409 +msgid "Some challenges of Poetry include:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:411 +msgid "Poetry, by default, pins dependencies using an \"upper bound\" limit specified with the `^` symbol by default. However, this behavior can be over-written by specifying the dependency when you use `Poetry add` as follows: `poetry add \"requests>=2.1\"` See breakout below for more discussion on issues surrounding upper-bounds pinning." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:412 +msgid "_Minor Challenge:_ The way Poetry currently adds metadata to your pyproject.toml file does not follow current Python standards. However, this is going to be addressed with Poetry release version 2.0." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:414 +msgid "Poetry is an excellent tool. Use caution when using it to pin dependencies as Poetry's approach to pinning can be problematic for many builds. If you use Poetry, we strongly suggest that you override the default upper bound dependency option." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:420 +msgid "Challenges with Poetry dependency pinning" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:423 +msgid "By default, Poetry pins dependencies using `^` by default. This `^` symbol means that there is an \"upper bound\" to the dependency. Thus poetry won't bump a dependency version to a new major version. Thus, if your package uses a dependency that is at version 1.2.3, Poetry will never bump the dependency to 2.0 even if there is a new major version of the package. Poetry will instead bump up to 1.9.x." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:429 +msgid "Poetry does this because it adheres to strict semantic versioning which states that a major version bump (from 1.0 to 2.0 for example) means there are breaking changes in the tool. However, not all tools follow strict semantic versioning. [This approach has been found to be problematic by many of our core scientific packages.](https://iscinumpy.dev/post/bound-version-constraints/)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:434 +msgid "This approach also won't support others ways of versioning tools, for instance, some tools use [calver](https://calver.org/) which creates new versions based on the date." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:438 +msgid "Using Setuptools Back-end for Python Packaging with Build Front-end" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:440 +msgid "[Setuptools](https://setuptools.pypa.io/en/latest/) is the most mature Python packaging build tool with [development dating back to 2009 and earlier](https://setuptools.pypa.io/en/latest/history.html#). Setuptools also has the largest number of community users (according to the PyPA survey). Setuptools does not offer a user front-end like Flit, Poetry and Hatch offer. As such you will need to use other tools such as **build** to create your package distributions and **twine** to publish to PyPI." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:448 +msgid "While setuptools is the most commonly used tool, we encourage package maintainers to consider using a more modern tool for packaging such as Poetry, Hatch or PDM." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:451 +msgid "We discuss setuptools here because it's commonly found in the ecosystem and contributors may benefit from understanding it." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:454 +msgid "Setuptools Features" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:456 +msgid "Some of features of setuptools include:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:458 +msgid "Fully customizable build workflow" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:459 +msgid "Many scientific Python packages use it." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:460 +msgid "It offers version control based package versioning using **setuptools_scm**" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:461 +msgid "It supports modern packaging using **pyproject.toml** for metadata" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:462 +msgid "Supports backwards compatibly for older packaging approaches." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:464 +msgid "Challenges using setuptools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:468 +msgid "Setuptools has a few challenges:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:470 +msgid "Setuptools does not support interactive features such as auto / tab completion by default if you are working in an IDE like VSCODE and using an editable install for development. [See notes here about pylance support](https://github.com/microsoft/pylance-release/blob/main/TROUBLESHOOTING.md#editable-install-modules-not-found). In comparison, tools such as flit, hatch, PDM support interactive features such as tab / auto completion when using an IDE like VSCODE or pycharm (as long as your version of pip is current!)." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:471 +msgid "Because **setuptools** has to maintain backwards compatibility across a range of packages, it is not as flexible in its adoption of modern Python packaging standards." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:474 +msgid "The above-mentioned backwards compatibility makes for a more complex code-base." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:475 +msgid "Your experience as a user will be less streamlined and simple using setuptools compared to other tools discussed on this page." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:477 +msgid "There are also some problematic default settings that users should be aware of when using setuptools. For instance:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:480 +msgid "setuptools will build a project without a name or version if you are not using a **pyproject.toml** file to store metadata." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:482 +msgid "setuptools also will include all of the files in your package repository if you do not explicitly tell it to exclude files using a **MANIFEST.in** file" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:1 +msgid "Learn about Building a Python Package" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:8 +msgid "Once you have published both package distributions (the source distribution and the wheel) to PyPI, you can then publish to conda-forge. The conda-forge requires an 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 "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:11 +msgid "You need to build your Python package in order to publish it to PyPI (or a conda channel). 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. NOTE: you need to publish a sdist to PyPI in order for conda-forge to properly build your package automatically." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:14 +msgid "What is building a Python package?" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:16 +msgid "To [publish your Python package](publish-python-package-pypi-conda) and make it easy for anyone to install, you first need to build it." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:18 +msgid "But, what does it mean to build a Python package?" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:20 +msgid "[As shown in the figure above](#pypi-conda-channels), when you build your Python package, you convert the source files into something called a distribution package. A distribution package contains your source code and metadata about the package, in the format required by the Python Package Index, so that it can be installed by tools like pip." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:23 +msgid "The term package used to mean many different things in Python and other languages. On this page, we adapt the convention of the [Python Packaging Authority](https://www.pypa.io/en/latest/) and refer to the product of the build step as a **distribution package**." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:27 +msgid "This process of organizing and formatting your code, documentation, tests and metadata into a format that both pip and PyPI can use, is called a build step." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:31 +msgid "Project metadata and PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:33 +msgid "The metadata that both build tools and PyPI uses to describe and understand your package is generally stored in a [pyproject.toml file](pyproject-toml-python-package-metadata). This metadata is used for several purposes:" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:35 +msgid "It helps whatever tool you use to build your package (pip, [pypa's Build](https://pypi.org/project/build/) or an end-to-end tool such as poetry, PDM or Hatch) understand how to build your package. Information it provides to your build tool includes:" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:37 +msgid "The `[build-system]` table in your pyproject.toml file tells pip what [build backend tool](build_backends) you wish to use for creating your sdist and wheel distributions." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:45 +msgid "And the dependencies section of your project table tells the build tool and PyPI what dependencies your project requires." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:54 +msgid "When the build tool creates your package distribution file (the file that you publish on PyPI), it also creates a METADATA file which PyPI can read and use to help users find your package. For example:" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:56 +msgid "The `classifiers = ` section of your `[project]` table in the pyproject.toml file provides information that users on PyPI can use to filter for packages that contain specific licenses or that support specific versions of python." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:73 +msgid "What happened to setup.py and setup.cfg for metadata?" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:76 +msgid "Project metadata used to be stored in either a setup.py file or a setup.cfg file. The current recommended practice for storing package metadata is to use a pyproject.toml file. [Learn more about the pyproject.toml file here.](pyproject-toml-python-package-metadata)" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:79 +msgid "An example - xclim" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:81 +msgid "When you publish to PyPI, you will notice that each package has metadata listed. Let's have a look at [xclim](https://pypi.org/project/xclim/), one of our [pyOpenSci packages](https://www.pyopensci.org/python-packages.html). Notice that on the PyPI landing page you see some metadata about the package including python, maintainer information and more. PyPI is able to populate this metadata because it was defined using correct syntax and classifiers by Xclim's maintainers, [pyproject.toml file](https://github.com/Ouranosinc/xclim/blob/master/pyproject.toml). This metadata when the xclim package is built, is translated into a distribution file that allows PyPI to read the metadata and print it out on their website." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:94 +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 "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:96 +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. NOTE: you need to publish a sdist to PyPI in order for conda-forge to properly build your package automatically." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:101 +msgid "This screenshot shows the metadata on PyPI for the xclim package. On it you can see the name of the license, the author and maintainer names keywords associated with the package and the base python version it requires which is 3.8." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:103 +msgid "PyPI screenshot showing metadata for the xclim package." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:110 +msgid "Here you see the maintainer metadata as it is displayed on PyPI. For xclim there are three maintainers listed with their profile pictures and github user names to the right." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:112 +msgid "Maintainer names and GitHub usernames for the xclim package as they are displayed on PyPI. This information is recorded in your pyproject.toml and then processed by your build tool and stored in your packages sdist and wheel distributions." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:115 +msgid "How to create the distribution format that PyPI and Pip expects?" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:117 +msgid "You could in theory create your own scripts to organize your code the way PyPI wants it to be. However, just like there are packages that handle known structures such as Pandas for data frames and Numpy for arrays, there are packages and tools that help you create package build distribution files." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:121 +msgid "There are a suite of packaging tools that can either help you with the entire packaging process or just one step of the process. For instance setuptools is a commonly used build back end that can be used to create your sdist and wheel. Whereas tools like Hatch, PDM, Poetry and flit help with other parts of the packaging process." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:127 +msgid "While this can cause some confusion and complexity in the packaging ecosystem - for the most part, each tool provides the same distribution output (with minor differences that most users may not care about). Learn more about those tools on this page." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:133 +msgid "Below, you will learn about the two distribution files that PyPI expects you to publish: sdist and wheel. You will learn about their structure and what files belong in each." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:136 +msgid "There are two core distribution files that you need to create to publish your Python package to PyPI source distribution (often called an sdist) and wheel. The sdist contains the raw source code for your package. The wheel (.whl) contains the built / compiled files that can be directly installed onto anyones' computer." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:142 +msgid "Learn more about both distributions below." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:145 +msgid "If your package is a pure python package with no additional build / compilation steps then the sdist and wheel distributions will have similar content. However if your package has extensions in other languages or is more complex in its build, the two distributions will be very different." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:150 +msgid "Also note that we are not discussing conda build workflows in this section. [You can learn more about conda builds here.](https://conda.io/projects/conda-build/en/latest/user-guide/tutorials/index.html)" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:155 +msgid "What is a source distribution (sdist)" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:157 +msgid "**Source files** are the unbuilt files needed to build your package. These are the \"raw / as-is\" files that you store on GitHub or whatever platform you use to manage your code." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:161 +msgid "Source Distributions (**S** + **Dist**) are referred to as sdist. As the name implies, a SDIST contains the source code; it has not been built or compiled in any way. Thus, when a user installs your source distribution using pip, pip needs to run a build step first. For this reason, you could define a source distribution as a compressed archive that contains everything required to build a wheel (except for project dependencies) without network access." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:165 +msgid "Sdist is normally stored as a `.tar.gz` archive (often called a \"tarball\"). Thus, when a user installs your source distribution using pip, pip needs to run a build step first." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:167 +msgid "Below is an example sdist for the stravalib Python package:" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:219 +msgid "GitHub archive vs sdist" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:221 +msgid "When you make a release on GitHub, it creates a `git archive` that contains all of the files in your GitHub repository. While these files are similar to an sdist, these two archives are not the same. The sdist contains a few other items including a metadata directory and if you use `setuptools_scm` or `hatch_vcs` the sdist may also contain a file that stores the version." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:229 +msgid "What is a Python wheel (whl):" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:231 +msgid "A wheel file is a ZIP-format archive whose filename follows a specific format (below) and has the extension `.whl`. The `.whl` archive contains a specific set of files, including metadata that are generated from your project's pyproject.toml file. The pyproject.toml and other files that may be included in source distributions are not included in wheels because it is a built distribution." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:238 +msgid "The wheel (.whl) is your built binary distribution. **Binary files** are the built / compiled source files. These files are ready to be installed. A wheel (**.whl**) is a **zip** file containing all of the files needed to directly install your package. All of the files in a wheel are binaries - this means that code is already compiled / built. Wheels are thus faster to install - particularly if you have a package that requires build steps." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:240 +msgid "The wheel does not contain any of your package's configuration files such as **setup.cfg** or **pyproject.toml**. This distribution is already built so it's ready to install." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:244 +msgid "Because it is built, the wheel file will be faster to install for pure Python projects and can lead to consistent installs across machines." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:252 +msgid "Wheels are also useful in the case that a package needs a **setup.py** file to support a more complex build. In this case, because the files in the wheel bundle are pre built, the user installing doesn't have to worry about malicious code injections when it is installed." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:259 +msgid "The filename of a wheel contains important metadata about your package." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:261 +msgid "Example: **stravalib-1.1.0.post2-py3-none.whl**" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:263 +msgid "name: stravalib" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:264 +msgid "version: 1.1.0" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:265 +msgid "build-number: 2 (post2) [(read more about post here)](https://peps.python.org/pep-0440/#post-release-separators)" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:266 +msgid "py3: supports Python 3.x" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:267 +msgid "none: is not operating system specific (runs on windows, mac, linux)" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:268 +msgid "any: runs on any computer processor / architecture" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:270 +msgid "What a wheel file looks like when unpacked (unzipped):" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:304 +msgid "[Read more about the wheel format here](https://pythonwheels.com/)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:1 +msgid "Python Package Structure for Scientific Python Projects" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:3 +msgid "There are two different layouts that you will commonly see within the Python packaging ecosystem: src and flat layouts. Both layouts have advantages for different groups of maintainers." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:8 +msgid "We strongly suggest, but do not require, that you use the **src/** layout (discussed below) for creating your Python package. This layout is also recommended in the [PyPA packaging guide tutorial](https://packaging.python.org/en/latest/tutorials/packaging-projects/)." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:12 +msgid "pyOpenSci will never require a specific package structure for peer review" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:15 +msgid "We understand that it would take significant effort for existing maintainers to move to a new layout." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:18 +msgid "The overview on this page presents recommendations that we think are best for someone getting started with Python packaging or someone who's package has a simple build and might be open to moving to a more fail-proof approach." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:22 +msgid "Other resources you can check out:" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:23 +msgid "[PyPA's overview of src vs flat layouts](https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:26 +msgid "You can use tools like Hatch to quickly create a modern Python package structure. Check out our quickstart tutorial:" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:29 +msgid "Want to learn how to create the structure to build your package? Click here." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:37 +msgid "What is the Python package source layout?" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:39 +msgid "An example of the **src/package** layout structure is below." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:61 +msgid "Note the location of the following directories in the example above:" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:63 +msgid "**docs/:** Discussed in our docs chapter, this directory contains your user-facing documentation website. In a **src/** layout docs/ are normally included at the same directory level as the **src/** folder." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:64 +msgid "**tests/** This directory contains the tests for your project code. In a **src/** layout, tests are normally included at the same directory level as the **src/** folder." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:65 +msgid "**src/package/**: this is the directory that contains the code for your Python project. \"Package\" is normally your project's name." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:67 +msgid "Also in the above example, notice that all of the core documentation files that pyOpenSci requires live in the root of your project directory. These files include:" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:71 +msgid "CHANGELOG.md" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:72 +msgid "CODE_OF_CONDUCT.md" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:73 +msgid "CONTRIBUTING.md" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:74 +msgid "LICENSE.txt" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:75 +msgid "README.md" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:79 +msgid "Click here to read about our packaging documentation requirements." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:86 +msgid "Example scientific packages that use **src/package** layout" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:88 +msgid "[Sourmash](https://github.com/sourmash-bio/sourmash)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:89 +msgid "[bokeh](https://github.com/bokeh/bokeh)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:90 +msgid "[openscm](https://github.com/openscm/openscm-runner)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:91 +msgid "[awkward](https://github.com/scikit-hep/awkward)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:92 +msgid "[poliastro](https://github.com/poliastro/poliastro/)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:96 +msgid "The src/ layout and testing" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:98 +msgid "The benefit of using the **src/package** layout is that it ensures tests are run against the installed version of your package rather than the files in your package working directory. If you run your tests on your files rather than the installed version of your package, you may be missing issues that users encounter when your package is installed." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:104 +msgid "If `tests/` are outside the **src/package** directory, they aren't included in the package's [wheel](python-wheel). This makes your package size slightly smaller, which places a smaller storage burden on PyPI, and makes them faster to fetch." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:106 +msgid "[Read more about reasons to use the **src/package** layout](https://hynek.me/articles/testing-packaging/)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:108 +msgid "How Python discovers and prioritizes importing modules" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:110 +msgid "By default, Python adds a module in your current working directory to the front of the Python module search path." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:112 +msgid "This means that if you run your tests in your package's working directory, using a flat layout, `/package/module.py`, Python will discover `package/module.py` file before it discovers the installed package." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:114 +msgid "However, if your package lives in a src/ directory structure **src/package**, then it won't be added to the Python path by default. This means that when you import your package, Python will be forced to search the active environment (which has your package installed)." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:116 +msgid "Note: Python versions 3.11 and above have a path setting that can be adjusted to ensure the priority is to use installed packages first (e.g., `PYTHONSAFEPATH`)." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:119 +msgid "Don't include tests in your package wheel" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:121 +msgid "Writing [tests](tests-intro) for your package is important; however, we do not recommend including tests as part of your [package wheel](python-wheel) by default. However, not including tests in your package distribution will make it harder for people other than yourself to test whether your package runs properly on their system. If you have a small test suite (Python files + data), and think your users may want to run tests locally on their systems, you can include tests by moving the `tests/` directory into the **src/package** directory (see example below)." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:130 +msgid "Including the **tests/** directory in your **src/package** directory ensures that tests will be included in your package's [wheel](python-wheel)." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:132 +msgid "Be sure to read the [pytest documentation for more about including tests in your package distribution](https://docs.pytest.org/en/7.2.x/explanation/goodpractices.html#choosing-a-test-layout-import-rules)." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:134 +msgid "Challenges with including tests and data in a package wheel" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:137 +msgid "Tests, especially when accompanied by test data, can create a few small challenges, including:" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:139 +msgid "Take up space in your distribution, which will build up over time as storage space on PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:140 +msgid "Large file sizes can also slow down package installation." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:142 +msgid "However, in some cases, particularly in the scientific Python ecosystem, you may need to include tests." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:145 +msgid "**Don't include test suite datasets in your package**" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:147 +msgid "If you include your tests in your package distribution, we strongly discourage you from including data in your test suite directory. Rather, host your test data in a repository such as Figshare or Zenodo. Use a tool such as [Pooch](https://www.fatiando.org/pooch/latest/) to access the data when you (or a user) runs tests." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:153 +msgid "For more information about Python package tests, see the [tests section of our guide](tests-intro)." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:155 +msgid "The **src/package** layout is semantically more clear. Code is always found in the **src/package** directory, `tests/` and `docs/`are in the root directory." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:159 +msgid "If your package tests require data, do NOT include that data within your package structure. Including data in your package structure increases the size of your distribution files. This places a maintenance toll on repositories like PyPI and Anaconda.org that have to deal with thousands of package uploads." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:166 +msgid "Click here for a quickstart tutorial on creating your Python package." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:176 +msgid "What is the flat Python package layout?" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:178 +msgid "Many scientific packages use the **flat-layout** given:" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:180 +msgid "This layout is used by many core scientific Python packages such as NumPy, SciPy, and Matplotlib." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:181 +msgid "Many Python tools depend upon tools in other languages and/or complex builds with compilation steps. Many maintainers prefer features of the flat layout for more complex builds." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:185 +msgid "While we suggest that you use the **src/package** layout discussed above, it's important to also understand the flat layout, especially if you plan to contribute to a package that uses this layout." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:189 +msgid "Why most scientific Python packages do not use source" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:192 +msgid "In most cases, moving to the **src/package** layout for larger scientific packages that already use a flat layout would consume significant time." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:195 +msgid "However, the advantages of using the **src/package** layout for a beginner are significant. As such, we recommend that you use the **src/package** layout if you are creating a new package." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:198 +msgid "Numerous packages in the ecosystem [have had to move to a **src/package** layout](https://github.com/scikit-build/cmake-python-distributions/pull/145)." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:202 +msgid "What does the flat layout structure look like?" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:204 +msgid "The flat layout's primary characteristics are:" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:206 +msgid "The source code for your package lives in a directory with your package's name in the root of your directory" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:208 +msgid "Often the `tests/` directory also lives within that same `package` directory." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:210 +msgid "Below you can see the recommended structure of a scientific Python package using the flat layout." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:232 +msgid "Benefits of using the flat layout in your Python package" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:234 +msgid "There are some benefits to the scientific community in using the flat layout." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:236 +msgid "This structure has historically been used across the ecosystem and packages using it are unlikely to change." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:238 +msgid "You can import the package directly from the root directory. For some this is engrained in their respective workflows. However, for a beginner the danger of doing this is that you are not developing and testing against the installed version of your package. Rather, you are working directly with the flat files." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:244 +msgid "Core scientific Python packages that use the flat layout" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:247 +msgid "[numpy](https://github.com/numpy/numpy)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:248 +msgid "[scipy](https://github.com/scipy/scipy)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:249 +msgid "[pandas](https://github.com/pandas-dev/pandas)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:250 +msgid "[xarray](https://github.com/pydata/xarray)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:251 +msgid "[Jupyter-core](https://github.com/jupyter/jupyter_core)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:252 +msgid "[Jupyter notebook](https://github.com/jupyter/notebook)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:253 +msgid "[scikit-learn](https://github.com/scikit-learn/scikit-learn)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:255 +msgid "It would be a significant maintenance cost and burden to move all of these packages to a different layout. The potential benefits of the source layout for these tools are not worth the maintenance investment." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:1 +msgid "Creating New Versions of Your Python Package" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:6 +msgid "Key Takeways" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:8 +msgid "Follow [semantic versioning guidelines (SemVer) rules](https://semver.org/) when bumping (increasing) your Python's package version; for example a major version bump (version 1.0 --> 2.0) equates to breaking changes in your package's code for a user." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:9 +msgid "You may want to consider using a plugin like hatch_vsc for managing versions of your package - if you want to have a GitHub only release workflow." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:10 +msgid "Otherwise most major package build tools such as Hatch, Flit and PDM have a version feature that will help you update your package's version" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:11 +msgid "Avoid updating your packages version number manually by hand in your code!" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:14 +msgid "pyOpenSci recommends that you follow the [Python PEP 440](https://peps.python.org/pep-0440) which recommends using [semantic versioning guidelines](https://www.python.org/dev/peps/pep-0440/#semantic-versioning) when assigning release values to new versions of your Python package." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:18 +msgid "[Semantic versioning](https://semver.org/) is an approach to updating package versions that considers the type and extent of a change that you are making to the package code. Being consistent with how and when you update your package versions is important as:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:23 +msgid "It helps your users (which might include other developers that depend on your package) understand the extent of changes to a package." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:24 +msgid "It helps your development team make decisions about when to bump a package version based on standard rules." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:26 +msgid "Consistent version increases following semver rules mean that values of your package version explain the extent of the changes made in the code base from version to version. Thus your package version numbers become \"expressive\" in the same way that naming code variables well can [make code expressive](https://medium.com/@daniel.oliver.king/writing-expressive-code-b69ef7a5a2fa)." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:28 +msgid "A note about versioning" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:29 +msgid "In some cases even small version changes can turn a package update into a breaking change for some users. What is also important is that you document how you version your code and if you can, also document your deprecation policy for code." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:37 +msgid "SemVer rules" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:39 +msgid "Following SemVer, your bump your package version to a:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:41 +msgid "patch (1.1.1 --> 1.1.**2**)" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:42 +msgid "minor (1.1.1 --> 1.**2**.1)" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:43 +msgid "major (1.1.1 --> **2**.1.1)" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:45 +msgid "version number change based on the following rules:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:47 +msgid "Given a version number MAJOR.MINOR.PATCH, increment the:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:49 +msgid "**MAJOR version** when you make incompatible API changes" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:50 +msgid "**MINOR version** when you add functionality in a backwards compatible manner" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:51 +msgid "**PATCH version** when you make backwards compatible bug fixes Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:56 +msgid "Some people prefer to use [calver](https://calver.org/index.html) for versioning. It may be a simpler-to-use system given it relies upon date values associated with released versions. However, calver does not provide a user with a sense of when a new version might break an existing build. As such we still suggest semver." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:59 +msgid "pyOpenSci will never require semver in a peer review as long as a package has a reasonable approach to versioning!" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:63 +msgid "Avoid manually updating Python package version numbers if you can" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:65 +msgid "Often times you may want to have your package version value in multiple locations. One example of this is that it might be both an attribute in your package **version** and also called in your documentation." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:70 +msgid "We recommend that you avoid manual updates of your package version number to avoid human-error. It is better practice to keep your version number in one location." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:74 +msgid "If you can't implement a single location version, then consider using a tool like hatch, PDM or bump2version that will update the version values for you - throughout your package." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:78 +msgid "Below we discuss some tools that you can use to manage updating Python package versions." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:83 +msgid "Tools to manage versions for your Python package" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:85 +msgid "There are a handful of tools that are widely used in the scientific ecosystem that you can use to manage your package versions. Some of these tools are built into or work with your chosen [packaging build tools that discussed in this chapter.](python-package-build-tools)" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:91 +msgid "Below, we provide an overview of these tools." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:97 +msgid "There are three general groups of tools that you can use to manage package versions:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:100 +msgid "**semantic release tools:** These tools will automagically determine what type of version bump to use using the text in your commit messages. Below we discuss [Python Semantic Release](https://python-semantic-release.readthedocs.io/en/latest/) as a Python tool that implements a semantic versioning approach." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:102 +msgid "**Manual incremental bump tools:** Tools like [Hatch](https://hatch.pypa.io/latest/version/) offer version bumping within your package. Normally this is implemented at the command link for instance `hatch version major` would bump your project from 0.x to 1.0." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:103 +msgid "**Version Control System tools:** Finally there are tools that rely on your version control system to track versions. These tools often are plugins to your package build tool (ex: setuptools build or hatchling). We discuss this option below assuming that you are using **.git tags** and **GitHub** to manage your package repository." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:105 +msgid "Semantic release, vs version control based vs manual version bumping" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:107 +msgid "Generally semantic release and version control system tools can be setup to run automatically on GitHub using GitHub Actions. This means that you can create a workflow where a GitHub release and associated new version tag is used to trigger an automated build that:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:113 +msgid "Builds your package and updates the version following the new tag" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:114 +msgid "Tests the build and publishes to test PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:115 +msgid "Publishes the package to PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:118 +msgid "Bumping a package version refers to the step of increasing the package version after a set number of changes have been made to it. For example, you might bump from version 0.8 to 0.9 of a package or from 0.9 to 1.0." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:122 +msgid "Using semantic versioning, there are three main \"levels\" of versions that you might consider:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:125 +msgid "Major, minor and patch. These are described in more detail below." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:128 +msgid "Tools for bumping Python package versions" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:130 +msgid "In this section we discuss the following tools for managing your Python package's version:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:133 +msgid "hatch &" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:134 +msgid "hatch_vcs plugin for hatchling" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:135 +msgid "setuptools-scm" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:136 +msgid "python-semantic-version" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:138 +msgid "Tool 1: Hatch and other build tools that offer incremental versioning" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:140 +msgid "Many of the modern build tool front end tools offer version support that follow semantic versioning rules. These tools are different from Python Semantic Version in that they do not require specific commit messages to implement version. Rather, they allow you to update the version at the command line using commands such as:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:146 +msgid "`tool-name version update major`" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:147 +msgid "`tool-name version update minor`" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:149 +msgid "[Hatch](https://hatch.pypa.io/latest/version/), for instance offers `hatch version minor` which will modify the version of your package incrementally. With **Hatch** the version value will be found in your `pyproject.toml` file. " +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:152 +msgid "Hatch (or other tools like PDM) Pros" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:154 +msgid "Easy to use version updates locally using a single tool!" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:156 +msgid "Hatch (or other tools like PDM) Cons" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:158 +msgid "There will be some setup involved to ensure package version is updated throughout your package" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:160 +msgid "Tool 2: Hatch_vcs & hatchling build back-end" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:162 +msgid "[hatch_vcs](https://github.com/ofek/hatch-vcs) is a versioning tool that allows you to manage package versions using **git tags**. Hatch_vcs creates a **\\_version.py** file in your package ecosystem that keeps track of the package's current version." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:167 +msgid "Hatch keeps track of your package's version in a `_version.py` file. Storing the version in a single file managed by Hatch provides your package with a \"single source of truth\" value for the version number. This in turn eliminates potential error associated with manually updating your package's version." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:173 +msgid "When you (or your CI system) build your package, hatch checks the current tag number for your package. If it has increased, it will update the **\\_version.py** file with the new value." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:176 +msgid "Thus, when you create a new tag or a new release with a tag and build your package, Hatch will access the new tag value and use it to update your package version." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:179 +msgid "To use **hatch_vcs** you will need to use the **hatchling** build back end." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:182 +msgid "Hatchling can also be used with any of the modern build tools including **Flit** and **PDM** if you prefer those for your day to day workflow." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:187 +msgid "Hatch example setup in your pyproject.toml" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:196 +msgid "**Hatch_vcs** supports a fully automated package release and build, and push to PyPI workflow on GitHub." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:206 +msgid "If you use **setuptools_scm**, then you might find **hatch_vcs** and **hatchling** to be the modern equivalent to your current setuptools / build workflow." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:209 +msgid "hatch_vcs Pros" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:211 +msgid "Hatch supports modern Python packaging standards" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:212 +#: ../../package-structure-code/python-package-versions.md:238 +msgid "It creates a single-source file that contains your package version." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:213 +#: ../../package-structure-code/python-package-versions.md:239 +msgid "You never manually update the package version" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:214 +#: ../../package-structure-code/python-package-versions.md:240 +msgid "You can automate writing the version anywhere in your package including your documentation!" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:215 +#: ../../package-structure-code/python-package-versions.md:241 +msgid "It supports a purely GitHub based release workflow. This simplifies maintenance workflows." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:216 +#: ../../package-structure-code/python-package-versions.md:242 +msgid "Version number is updated in your package via a hidden `_version.py` file. There is no manual configuration updates required." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:217 +#: ../../package-structure-code/python-package-versions.md:243 +msgid "While we like detailed commit messages (See Python Semantic Version below), we know that sometimes when maintaining a package specific guidelines around commit messages can be hard to apply and manage." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:219 +msgid "hatch_vcs Cons" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:221 +msgid "In a CI workflow you will end up manually entering or creating the version number via a tag on GitHub. But you could locally develop a build to \"bump\" tag versions" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:224 +msgid "Tool 3: setuptools-scm versioning using git tags" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:226 +msgid "[`Setuptools_scm`](https://github.com/pypa/setuptools_scm/) is an extension that you can use with setuptools to manage package versions. **Setuptools_scm** operates the same way that **hatch_vcs** (discussed above) does. It stores a version in a **\\_version.py** file and relies on (**git**) tags to determine the package's current version." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:232 +msgid "If you are using **setuptools** as your primary build tool, then `*setuptools-scm` is a good choice as:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:236 +msgid "setuptools_scm Pros" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:244 +msgid "**setuptools** is still the most commonly used Python packaging build tool" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:246 +msgid "setuptools_scm Cons" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:248 +msgid "In a CI workflow you will end up manually entering or creating the version number via a tag on GitHub." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:249 +msgid "Not well documented" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:250 +msgid "Because setuptools will always have to support backwards compatibility it will always be slower in adopting modern Python packaging conventions." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:252 +msgid "As such you might consider using a more modern tool such as **hatch_vcs** and **hatchling** to build your package and manage package versions." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:264 +msgid "Tool 4: [Python semantic release](https://python-semantic-release.readthedocs.io/en/latest/)" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:266 +msgid "Python semantic release uses a commit message workflow that updates the version of your package based on keywords found in your commit messages. As the name implies, Python Semantic Release follows semver release rules." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:271 +msgid "With Python Semantic Release, versions are triggered using specific language found in a git commit message." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:274 +msgid "For example, the words `fix(attribute_warning):` trigger Python Semantic Release to implement a **patch** version bump. For instance if your package was at version 1.1.0 and you made the commit below with the words fix(text-here), Python Semantic Release would bump your package to version 1.1.1." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:284 +msgid "Similarly a feature (`feat()`) triggers a minor version bump. For example from version 1.1 to version 1.2" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:292 +msgid "You can find a thoughtful discussion of python semantic version [in this Python package guide](https://py-pkgs.org/07-releasing-versioning#automatic-version-bumping). Note that the guide hasn't been updated since 2020 and will potentially be updated in the future! But for now, some of the commands are dated but the content is still excellent." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:295 +msgid "Python Semantic Release Pros" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:297 +msgid "Follows semver versioning closely" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:298 +msgid "Enforces maintainers using descriptive commit messages which can simplify troubleshooting and ensure a cleaner and more self-describing git history." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:300 +msgid "Python Semantic Release Cons" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:302 +msgid "Requires very specific commit language to work. In practice some maintainers and contributors may not be able to maintain that level of specificity in commit messages (NOTE: there are bots that will check git commit messages in a repo)" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:303 +msgid "Release happens at the command line. This makes is harder to implement a GitHub based release workflow as the wrong commit message could trigger a release." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:304 +msgid "The version number is manually updated in a configuration file such as `pyproject.toml` vs. in a package **\\_version.py** file." +msgstr "" diff --git a/locales/templates/LC_MESSAGES/package-structure-code.pot b/locales/templates/LC_MESSAGES/package-structure-code.pot new file mode 100644 index 00000000..351a7521 --- /dev/null +++ b/locales/templates/LC_MESSAGES/package-structure-code.pot @@ -0,0 +1,3648 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2025, pyOpenSci +# This file is distributed under the same license as the pyOpenSci Python Package Guide package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: pyOpenSci Python Package Guide \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-04-30 18:44-0600\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../package-structure-code/code-style-linting-format.md:1 +msgid "Python Package Code Style, Format and Linters" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:3 +#: ../../package-structure-code/publish-python-package-pypi-conda.md:12 +msgid "Take Aways" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:5 +msgid "pyOpenSci requires authors to follow PEP 8 code format guidelines" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:6 +msgid "Setting up a code formatters like Black and isort will help you enforce PEP 8 style guidelines and also consistent, readable code format" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:7 +msgid "Some commonly used tools are: Black, Isort, flake8, Ruff" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:8 +msgid "You can also setup pre-commit hooks which will run code formatters locally each time you make a commit." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:10 +msgid "[precommit.ci](https://pre-commit.ci/) is a bot that you can add to your GitHub repository. It will automagically apply code format to every PR using the tools specified in your pre-commit-config.yaml file. It can save significant time and make contributions easier for new contributors." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:11 +msgid "Automation is good! By making code quality tools care of your code, you can focus on structural and high values tasks." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:14 +msgid "Consistent code format and style is useful to both your package and across the scientific Python ecosystem because using similar formats makes code easier to read." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:18 +msgid "For instance, if you saw a sentence like this one without any spaces, or punctuation, it would take your brain longer to process it." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:25 +msgid "pyOpenSci peer review process requires that you to follow standard [Python PEP 8 format rules](https://peps.python.org/pep-0008/) as closely as you can." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:29 +msgid "pyOpenSci doesn't require you to use a specific code format tool. However, we do look for consistency and readability in code style. Below you will find a discussion of:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:33 +msgid "The benefits of using linters and code format tools in your workflow" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:34 +msgid "Some commonly used tools in the scientific Python space" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:35 +msgid "Setting up pre-commit hooks and the pre-commit.ci bot to make using code format tools in daily workflows and in pull requests on GitHub easier." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:38 +msgid "Use a code format tool (or tools) to make your life easier" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:40 +msgid "We suggest that you use a code format tool, or a set of format tools, because manually applying all of the PEP 8 format specifications is both time consuming for maintainers and can be a road block for potential new contributors. Code formatters will automagically reformat your code for you, adhering to PEP 8 standards and applying consistent style decisions throughout." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:46 +msgid "Setting up a code format suite of tools will:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:48 +msgid "Save you and your maintainer team time in fixing PEP 8 inconsistencies." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:49 +msgid "Ensure that format and style is consistent across your entire code-base." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:50 +msgid "Avoid lengthy discussions with contributors and other maintainers about personalized code format preferences during reviews." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:52 +msgid "Avoid pure visual edits in the code base so that code reviews focus on added value" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:54 +msgid "Many packages use a suite of tools to apply code format rules, taking the work out of manually implementing code format requirements." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:57 +msgid "Consistent code format across packages within the (scientific) Python ecosystem, will also broadly make code easier to scan, understand and contribute to." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:60 +msgid "Linting vs format and style" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:62 +msgid "Before we dive in let's get a few definitions out of the way." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:64 +msgid "Code Linting" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:66 +msgid "A code linter is a tool that will review your code and identify errors or issues. A linter typically does not modify your code. It will tell you what the error is and on what line it was discovered. Flake8, discussed below, is an example of a commonly-used code linter." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:71 +msgid "Code Formatters (and stylers)" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:73 +msgid "Code formatters will reformat your code for you. Python focused code formatters often follow PEP 8 standards. However, they also make stylistic decisions about code consistency." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:77 +msgid "Black is an example of a commonly-used code formatter. Black both applies PEP 8 standards while also making decisions about things like consistent use of double quotes for strings, and spacing of items in lists." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:81 +msgid "You will learn more about Black below." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:83 +msgid "Code linting, formatting and styling tools" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:85 +msgid "Black" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:87 +msgid "[Black](https://black.readthedocs.io/en/stable/) is a code formatter. Black will automagically (and _unapologetically_) fix spacing issues and ensure code format is consistent throughout your package. Black also generally adheres to PEP 8 style guidelines with some exceptions. A few examples of those exceptions are below:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:93 +msgid "Black defaults to a line length of 88 (79 + 10%) rather than the 79 character `PEP 8` specification. However, line length is a setting can be manually overwritten in your Black configuration." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:94 +msgid "Black will not adjust line length in your comments or docstrings." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:95 +msgid "This tool will not review and fix import order (you need `isort` or `ruff` to do that - see below)." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:98 +msgid "If you are interested in seeing how Black will format your code, you can use the [Black playground](https://black.vercel.app/)" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:102 +msgid "Using a code formatter like Black will leave you more time to work on code function rather than worry about format." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:105 +msgid "Flake8" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:107 +msgid "To adhere to Python `pep8` format standards, you might want to add [flake8](https://flake8.pycqa.org/en/latest/) to your code format toolbox." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:111 +msgid "flake8 will:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:113 +msgid "Flag every line in your code that extends beyond 79 characters (including those in docstrings and comments)" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:114 +msgid "Flag spacing issues that conflict with PEP 8 guidelines such as missing spaces after commas" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:116 +msgid "Flake8 also flags unused imports and unused declared variables in your modules." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:119 +msgid "Below you can see the output of running `flake8 filename.py` at the command line for a Python file within a package called `stravalib`." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:123 +msgid "The line length standard for PEP 8 is 79 characters." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:125 +msgid "Notice that flake8 returns a list of issues that it found in the model.py module on the command line. The Python file itself is not modified. Using this output, you can fix each issue line by line manually." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:140 +msgid "Isort" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:142 +msgid "Python imports refer to the Python packages that a module in your package requires. Imports should always be located at the top of each Python module in your package." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:146 +msgid "[PEP 8 has specific standards for the order of these imports](https://peps.python.org/pep-0008/#imports). These standards are listed below:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:148 +msgid "Imports should be grouped in the following order:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:150 +msgid "Standard library imports." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:151 +msgid "Related third party imports." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:152 +msgid "Local application/library specific imports." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:154 +msgid "While `flake8` will identify unused imports in your code, it won't fix or identify issues with the order of package imports." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:157 +msgid "`isort` will identify where imports in your code are out of order. It will then modify your code, automatically reordering all imports. This leaves you with one less thing to think about when cleaning up your code." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:162 +msgid "Example application of isort" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:164 +msgid "Code imports before `isort` is run:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:166 +msgid "Below, the `pandas` is a third party package, `typing` is a core `Python` package distributed with `Python`, and `examplePy.temperature` is a first-party module which means it belongs to the same package as the file doing the import. Also notice that there are no spaces in the imports listed below." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:176 +msgid "From the project root, run:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:182 +msgid "Python file `temporal.py` imports after `isort` has been run" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:189 +msgid "Ruff" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:191 +msgid "[Ruff](https://docs.astral.sh/ruff/) is a new addition to the code quality ecosystem, gaining some traction since its release. `ruff` is both a linter and a code formatter for Python, aiming to replace several tools behind a single interface. As such, `ruff` can be used at a replacement of all other tools mentioned here, or in complement to some of them." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:197 +msgid "`ruff` has some interesting features that distinguish it from other linters:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:199 +msgid "Linter configuration in `pyproject.toml`" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:200 +msgid "Several hundred rules included, many of which are automatically fixable" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:201 +msgid "Rules explanation, see [F403](https://docs.astral.sh/ruff/rules/undefined-local-with-import-star/) for an example" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:202 +msgid "Fast execution time, makes a quick feedback loop possible even on large projects." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:204 +msgid "Here is a simple configuration to get started with `ruff`. It would go into your `pyproject.toml`:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:212 +msgid "Depending on your project, you might want to add the following to sort imports correctly:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:219 +msgid "How to use code formatter in your local workflow" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:221 +msgid "Linters, code formatters and your favorite coding tools" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:223 +msgid "Linters can be run as a command-line tool as shown above. They also can be run within your favorite coding tool (e.g. VScode, pycharm, etc). For example, you might prefer to have tools like Black and isort run when you save a file. In some editors you can also setup shortcuts that run your favorite code format tools on demand." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:229 +msgid "Use pre-commit hooks to run code formatters and linters on commits" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:231 +msgid "You can also setup a `pre-commit hook` in your Python package repository." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:233 +msgid "A pre-commit hook is a tool that allows an action (or actions) to be triggered when you apply a commit to your git repository." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:236 +msgid "Pre-commit hook example workflow" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:238 +msgid "The precommit workflow looks like this: You type and run:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:241 +msgid "`git commit -m \"message here\"` at the command line" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:243 +msgid "Once you hit return, pre-commit will run any tools that you have configured in a **.pre-commit-config.yaml** file." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:245 +msgid "If the tools configured in the pre-commit hook run successfully without making changes or finding errors in your code, the commit will be applied to the repository." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:249 +msgid "If the tools configured in the hook find errors in your files, the commit will NOT be applied to the repository. Remember from the discussion above that a code formatter like Black will run and reformat your code. A linter like _flake8_ will provide you with some output that details where there are syntax issues in your code. You will then need to fix those issues, manually." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:256 +msgid "Once all of the fixes are applied you can re-add (stage) the files to be commit. And re-run your commit." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:260 +msgid "Diagram showing the steps of a pre-commit workflow from left to right." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:262 +msgid "The pre-commit workflow begins with you adding files that have changes to be staged in git. Next, you'd run git commit. When you run git commit, the pre-commit hooks will then run. In this example, Black, the code formatter and flake8, a linter both run. If all of the files pass Black and flake8 checks, then your commit will be recorded. If they don't, the commit is canceled. You will have to fix any flake8 issues, and then re-add / stage the files to be committed. [_Image Source_](https://ljvmiranda921.github.io/notebook/2018/06/21/precommits-using-black-and-flake8/*)" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:275 +msgid "If have a Python code-base and multiple maintainers actively working on the code, and you intend to run a tool like Black, be sure to coordinate across your team. An initial commit that applies Black to your entire package will likely change a significant amount of your code. This could lead to merge conflicts on open and new PR's before the new changes are merged." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:282 +msgid "General pre commit checks" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:284 +msgid "In addition to calling tools, Pre-commit also has a suite of [built in format hooks](https://github.com/pre-commit/pre-commit-hooks#hooks-available) that you can call. Some, such as `trailing-whitespace` can be also useful to add to your pre-commit workflow to ensure clean, streamlined code files." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:289 +msgid "An example pre-commit-config.yaml file is below with examples of how this is all setup." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:292 +msgid "Pre-commit.ci" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:294 +msgid "[Pre-commit.ci](https://pre-commit.ci) is a bot that may become your new best friend. This bot, when setup on a repo can be configured to do the following:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:297 +msgid "It will check every pull request using all of the pre-commit hook setting" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:298 +msgid "If you wish, it will also submit a pull request to your repo with pre-commit fixes, saving you, and new contributors the time of reformatting a pr that has format issues." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:301 +msgid "You can also call the bot on any pull request to run / and fix the code." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:303 +msgid "The pre-commit.ci bot uses the same pre-commit-config.yaml file that you use to setup pre-commit locally." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:306 +msgid "Setting up a bot like this can be valuable because:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:308 +msgid "It can make is easier for maintainers as they no longer have to worry at allows about fixing code format. The bot will do the work for them." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:310 +msgid "It can make it easier for new comers as they never have to setup pre-commit locally or worry about linting their code. They can even make small fixes to the code directly on GitHub without worry." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:312 +msgid "Setting up a git pre-commit hook" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:314 +msgid "To setup pre-commit locally, you need to do 3 things:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:316 +msgid "Install pre-commit (and include it as a development requirement in your repository)" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:326 +msgid "Create a .pre-commit-config.yaml file in the root of your package directory." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:328 +msgid "Below is an example **.pre-commit-cofig.yaml** file that can be used to setup the pre-commit hook and the pre-commit.ci bot if you chose to implement that too." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:336 +msgid "This file specifies a hook that will be triggered automatically before each `git commit`, in this case, it specifies a `flake8` using version `6.0.0`." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:339 +msgid "Install your pre-commit hook(s) using `pre-commit install`. This will install all of the hooks specified in the pre-commit yaml file into your environment." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:341 +msgid "Once you have done the above, you are ready to start working on your code. Pre-commit will run every time you run `git commit`." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:344 +msgid "Summary" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:346 +msgid "pyOpenSci suggests setting up a linter and a code styler for your package, regardless of whether you use pre-commit hooks, CI or other infrastructure to manage code format. Setting up these tools will give you automatic feedback about your code's structure as you (or a contributor) write it. And using a tool like black that format code for you, reduce effort that you need to make surrounding decisions around code format and style." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:1 +msgid "Complex Python package builds" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:3 +msgid "This guide is focused on packages that are either pure-python or that have a few simple extensions in another language such as C or C++." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:6 +msgid "In the future, we want to provide resources for packaging workflows that require more complex builds. If you have questions about these types of package, please [add a question to our discourse](https://pyopensci.discourse.group/) or open an [issue about this guide specifically in the GitHub repo for this guide](https://github.com/pyOpenSci/python-package-guide/issues). There are many nuances to building and distributing Python packages that have compiled extensions requiring non-Python dependencies at build time. For an overview and thorough discussion of these nuances, please see [this site.](https://pypackaging-native.github.io/)" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:8 +msgid "Pure Python Packages vs. packages with extensions in other languages" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:10 +msgid "You can classify Python package complexity into three general categories. These categories can in turn help you select the correct package frontend and backend tools." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:14 +msgid "**Pure-python packages:** these are packages that only rely on Python to function. Building a pure Python package is simpler. As such, you can chose a tool below that has the features that you want and be done with your decision!" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:16 +msgid "**Python packages with non-Python extensions:** These packages have additional components called extensions written in other languages (such as C or C++). If you have a package with non-Python extensions, then you need to select a build backend tool that allows additional build steps needed to compile your extension code. Further, if you wish to use a frontend tool to support your workflow, you will need to select a tool that supports additional build setups. We suggest that you chose build tool that supports custom build steps like Hatch." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:18 +msgid "**Python packages that have extensions written in different languages (e.g. Fortran and C++) or that have non Python dependencies that are difficult to install (e.g. GDAL):** These packages often have complex build steps (more complex than a package with just a few C extensions for instance). As such, these packages require tools such as [scikit-build](https://scikit-build.readthedocs.io/en/latest/) or [meson-python](https://mesonbuild.com/Python-module.html) to build. NOTE: you can use meson-python with PDM." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:21 +msgid "Mixing frontend and backend projects" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:23 +msgid "It is sometimes necessary or desirable to use a build frontend with an alternative build-backend. This is because some frontends do not have a default backend (`build`), and this choice is placed on the maintainer. Other backends (`hatch`) have a preferred backend (`hatchling`) but allow the maintainer to migrate to another, while some backends (`poetry`) only work with a single backend (`poetry-core`). Refer to (#python-package-build-tools) for more information about frontend and backend compatibility." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:29 +msgid "In this packaging guide we recommend using `hatch` along with its preferred backend `hatchling`. While this will be suitable for most packages, an alternate backend may be used with Hatch if needed when creating an extension module. A Python extension module is one that is made up, either in part or entirely, of compiled code. In this case the backend chosen (such as `meson-python`) must know how to compile the extension language and bind it to Python. `hatchling` does not know how to do this all on its own and must either make use of [plugins](https://hatch.pypa.io/1.9/plugins/about/) or be replaced by a backend that is already capable of building extension modules." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:37 +msgid "In order to use a different backend you will need to edit your project's `pyproject.toml`. If you have a `pyproject.toml` generated by the `hatch` command, or from following the packaging tutorial, you may have to make a change like this" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:8 +#: ../../package-structure-code/declare-dependencies.md:375 +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:22 +msgid "Todo" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:10 +msgid "keep this comment - https://github.com/pyOpenSci/python-package-guide/pull/106#issuecomment-1844278487 in this file for now - jeremiah did a nice inventory of common shells and whether they need quotes or not. It's really comprehensive. But do we want it in the guide?? it's really useful for more advanced users i think." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:12 +msgid "Following this comment: https://github.com/pyOpenSci/python-package-guide/pull/106#pullrequestreview-1766663571" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:15 +msgid "Jonny will add a section that talks about:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:17 +msgid "Why you specify dependencies How to specify dependencies When you use different specifiers" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:22 +msgid "Python Package Dependencies" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:24 +msgid "What is a package dependency?" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:26 +msgid "A Python package dependency refers to an external package or software that your Python project:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:29 +msgid "Needs to function properly." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:30 +msgid "Requires if someone wants to develop / work on improving your package locally or" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:31 +msgid "Requires if a user wants to add additional functionality (that is not core) to your package" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:33 +msgid "A dependency is not part of your project's codebase. It is a package or software that is called within the code of your project or during development of your package." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:37 +msgid "Understanding optional vs. required dependencies" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:38 +msgid "You can think about dependencies as being either optional or required. If they are required, they will be listed in the `dependencies` key in the `project` table of your `pyproject.toml` file. If they are optional, they will be listed in the `[optional.dependencies]` table of your `pyproject.toml`." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:40 +msgid "You will learn about both below." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:46 +msgid "There are two broad groups of Python package dependencies: those that are optional and those that are required. Required packages are those that a user needs to use your package. Optional dependencies are packages a user can chose to install to add functionality to your package. Within those 2 groups, there are three use cases that you can think about. 1. Core dependencies are **required** for a user to use your package. 2. Development dependencies are optional and only needed if someone wants to work on your package locally. 3. Finally feature dependencies are optional and add additional functionality to your package. Not all packages will have feature dependencies." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:51 +msgid "Required (or core) dependencies" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:53 +msgid "Required dependencies are called directly within your package's code. On this page we refer to these dependencies as **core dependencies** as they are needed in order to run your package. You should place your core or required dependencies in the `dependencies` key of the `[project]` table of your `pyproject.toml` file." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:56 +#: ../../package-structure-code/declare-dependencies.md:147 +msgid "Optional dependencies" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:58 +msgid "Optional dependencies dependencies can be optionally installed by users depending upon their needs. There are two broad groups of optional dependencies:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:61 +msgid "**Development dependencies**: These are dependencies that are required to support development of your package. They include tools to run tests such as `pytest`, linters (like `flake8` and `ruff`) and code formatters such as `black` and even automation tools such as `nox` or `tox` that run tasks." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:63 +msgid "**Feature dependencies:** These are dependencies that a user can chose to install to add functionality to your package." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:65 +msgid "When a Python project is installed, the Python package manager (either `pip` or `conda`) installs your package's dependencies automatically. This ensures that when you call a function in a specific dependency, it is available in your user's environment." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:70 +msgid "Dependencies can be added to your pyproject.toml file" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:72 +msgid "In the [pyproject.toml overview page](pyproject-toml-python-package-metadata), you learned how to set up a **pyproject.toml** file with basic metadata for your package. On this page, you will learn how to specify different types of dependencies in your `pyproject.toml`." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:79 +msgid "How do you declare dependencies?" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:81 +msgid "We recommend that you declare your dependencies using your `pyproject.toml` file. This ensures that all of the metadata associated with your package is declared in a single place, making it simpler for users and contributors to understand your package infrastructure." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:86 +msgid "Previously, it was common to use a `requirements.txt` file to declare package dependencies. However in recent years, the ecosystem has moved to storing this information in your **pyproject.toml** file. You may notice however that some projects still maintain a `requirements.txt` file for specific local development needs." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:92 +msgid "Other ways you may see packages storing dependencies" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:95 +msgid "If a project contains extensions written in other languages, you may need a `setup.py` file. Or you may contribute to a package that us using `setup.cfg` for dependency declaration. [Learn more about this in the setuptools documentation](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#declaring-required-dependency)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:100 +msgid "Add required dependencies to your pyproject.toml file" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:102 +msgid "Your core project dependencies need to be installed by a package manager such as `pip` or `conda` when a user installs your package. You can add those dependencies to the `dependencies` array located within the `[project]` table of your **pyproject.toml** file. This looks something like this:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:121 +msgid "Ideally, you should only list the packages that are necessary to install and use your package in the `dependencies` key in the `[project]` table. This minimizes the number of additional packages that your users must install as well as the number of packages that depend upon your package must also install." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:128 +msgid "Remember that fewer dependencies to install reduces the likelihood of version mismatches in user environments." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:131 +msgid "A dependency example" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:133 +msgid "Let's pretend you have a package called `plotMe` that creates beautiful plots of data stored in `numpy` arrays. To create your plots in the `plotMe` package, you use the `seaborn` package to stylize our plots and also `numpy` to process array formatted data." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:135 +msgid "In the example above, the plotMe package, depends upon two packages:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:137 +msgid "seaborn" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:138 +msgid "numpy" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:140 +msgid "This means that in order for plotMe to work in a user's `environment` when installed, you also need to ensure that they have both of those required `dependencies` installed in their environment too." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:142 +msgid "Declaring a dependency in your `pyproject.toml` file will ensure that it is listed as a required dependency when your package is published to PyPI and that a package manager (`pip` or `conda`) will automatically install it into a user's environment alongside your package:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:144 +msgid "`python -m pip install plotMe`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:149 +msgid "Optional dependencies for building your documentation, running your tests and building your package's distribution files are often referred to as development dependencies. These are the dependencies that a user needs to work on your package locally and perform tasks such as:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:151 +msgid "running your test suite" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:152 +msgid "building your documentation" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:153 +msgid "linting and other code cleanup tools" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:155 +msgid "These dependencies are considered optional, because they are not required to install and use your package. Feature dependencies are considered optional and should also be placed in the `[project.optional-dependencies]` table." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:158 +msgid "Optional dependencies can be stored in an `[project.optional-dependencies]` table in your **pyproject.toml** file." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:161 +msgid "It's important to note that within the `[project.optional-dependencies]` table, you can store additional, optional dependencies within named sub-groups. This is a different table than the dependencies array located within the `[project]` table discussed above which contains a single array with a single list of required packages." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:163 +msgid "Create optional dependency groups" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:165 +msgid "To declare optional dependencies in your **pyproject.toml** file:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:167 +msgid "Add a `[project.optional-dependencies]` table to your **pyproject.toml** file." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:168 +msgid "Create named groups of dependencies using the syntax:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:170 +msgid "`group-name = [\"dep1\", \"dep2\"]`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:172 +msgid "Installing packages from GitHub / Gitlab" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:175 +msgid "If you have dependencies that need to be installed directly from GitHub using a `git+https` installation approach, you can do so using the pyproject.toml file like so:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:185 +msgid "IMPORTANT: For security reasons, if your library depends on a GitHub-hosted project, you will need to point to a specific commit/tag/hash of that repository in order to upload your project to PyPI" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:190 +msgid "Below we've created three sets of optional development dependencies named: tests, docs and lint. We've also added a set of feature dependencies." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:213 +msgid "Additional dependency resources" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:215 +msgid "[Learn more: View PyPA's overview of declaring optional dependencies](https://packaging.python.org/en/latest/specifications/declaring-project-metadata/#dependencies-optional-dependencies)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:217 +msgid "[Dependency specifiers](https://packaging.python.org/en/latest/specifications/dependency-specifiers/)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:221 +msgid "Install dependency groups" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:226 +msgid "Diagram showing a Venn diagram with three sections representing the dependency groups listed above - docs feature and tests. In the center it says your-package and lists the core dependencies of that package seaborn and numpy. To the right are two arrows. The first shows the command python - m pip install your-package. It them shows how installing your package that way installs only the package and the two core dependencies into a users environment. Below is a second arrow with python -m pip install youPackage[tests]. This leads to an environment with both the package dependencies - your-package, seaborn and numpy and also the tests dependencies including pytest and pytest-cov" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:228 +msgid "When a user installs your package locally using `python -m pip install your-package` only your package and it's core dependencies get installed. When they install your package `python -m pip install your-package[tests]` pip will install both your package and its core dependencies plus any of the dependencies listed within the tests array of your `[project.optional-dependencies]` table." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:231 +msgid "Using `python -m pip install` vs. `pip install`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:233 +msgid "In all of the examples in this guide, you will notice we are calling `pip` using the syntax:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:236 +msgid "`python -m pip`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:238 +msgid "Calling pip using `python -m` ensures that the `pip` that you are using to install your package comes from your current active Python environment. We strongly suggest that you use this approach whenever you call `pip` to avoid installation conflicts." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:242 +msgid "To ensure this works as you want it to, activate your package's development environment prior to installing anything using `pip`." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:246 +msgid "You can install development dependencies using the groups that you defined above using the syntax:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:249 +msgid "`python -m pip install \".[docs]\"`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:251 +msgid "Above you install:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:252 +msgid "dependencies needed for your documentation (`docs`)," +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:253 +msgid "required package dependencies in the `dependencies` array and" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:254 +msgid "your package" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:256 +msgid "using pip. Below you install your package, required dependencies and optional test dependencies." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:259 +#: ../../package-structure-code/declare-dependencies.md:277 +msgid "`python -m pip install \".[tests]\"`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:261 +msgid "You can install multiple dependency groups in the `[project.optional-dependencies]` table using:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:263 +msgid "`python -m pip install \".[docs, tests, lint]\"`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:266 +msgid "For zsh shell users" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:270 +msgid "There are different shell applications that you and your package contributors might use." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:271 +msgid "zsh is the shell that comes by default on newer Mac OS computers" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:272 +msgid "Windows users may use a tool such as git bash" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:274 +msgid "Some shells don't support unquoted brackets (`[tests]`) which is why we add quotes to the command in this guide like this:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:279 +msgid "In some cases you may see commands without the quotes in guidebooks or contributing guides like the example below:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:282 +msgid "`python -m pip install your-package[tests]`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:284 +msgid "Calling your-package[tests] without the double quotes will work on some shells *but not all*." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:287 +msgid "Combining sets of dependencies" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:289 +msgid "Above we reviewed how to install dependencies from your `pyproject.toml`. In some cases you may want to group sets of dependencies like so:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:302 +msgid "The above allows you to install both the tests and docs dependency lists using the command:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:305 +msgid "`python -m pip install \".[dev]\"`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:308 +msgid "When you install dependencies using the above syntax:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:310 +msgid "`python -m pip install \".[tests, docs]\"`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:312 +msgid "`pip` will also install your package and its core dependencies." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:316 +msgid "Where does conda fit in?" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:319 +msgid "The `pyproject.toml` file allows you to list any Python package published on PyPI (or on GitHub/ GitLab) as a dependency. Once you create this file, declare dependencies, [build your package](python-package-distribution-files-sdist-wheel.md) and [publish your package to PyPI](publish-python-package-pypi-conda.md), people can install both your package and all of it's dependencies with one command." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:322 +msgid "`python -m pip install your-package`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:324 +msgid "This works great if your package is pure-python (no other languages used)." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:326 +msgid "Some packages, particularly in the scientific Python ecosystem, require dependencies that are not written in Python. Conda was created to support distribution of tools that have code written in both Python and languages other than Python." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:329 +msgid "Support conda users with environment.yml files" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:331 +msgid "The above workflow assumes that you want to publish your package on PyPI. And then you plan to publish to conda-forge (optionally), [by submitting a recipe using grayskull](https://www.pyopensci.org/python-package-guide/package-structure-code/publish-python-package-pypi-conda.html)." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:333 +msgid "If you want to support conda users, you may want to also maintain a conda environment that they can use to install your package. Maintaining a conda environment will also help you test that your package installs as you expect into a conda environment." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:336 +msgid "A note for conda users" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:339 +msgid "If you use a conda environment for developing your tool, keep in mind that when you install your package using `python -m pip install -e .` (or using pip in general), dependencies will be installed from PyPI rather than conda." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:341 +msgid "Thus, if you are running a conda environment, installing your package in \"editable\" mode risks dependency conflicts. This is particularly important if you have a spatial package that requires geospatial system libraries like GDAL or another system-level dependency." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:343 +msgid "Alternatively, you can install your package using `python -m pip install -e . --no-deps` to only install the package. And install the rest of your dependencies using a conda environment file." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:346 +msgid "Dependencies in Read the Docs" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:348 +msgid "Now that you have your dependencies specified in your project, you can use them to support other workflows such as publishing to Read the Docs." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:350 +msgid "[Read the Docs](https://readthedocs.org) is a documentation platform with a continuous integration / continuous deployment service that automatically builds and publishes your documentation." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:352 +msgid "If you are using Read the Docs to build your documentation, then you may need to install your dependencies using a **readthedocs.yaml** file." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:354 +msgid "Below is an example of installing the **docs** section of your dependency table in the pyproject.toml file within a readthedocs.yaml file." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:366 +msgid "Read the Docs and Python packages" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:370 +msgid "[Learn more about creating a `readthedocs.yaml` file here. ](https://docs.readthedocs.io/en/stable/config-file/index.html)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:371 +msgid "If you want to install dependencies using Poetry in Read the Docs, [you can learn more here.](https://docs.readthedocs.io/en/stable/build-customization.html#install-dependencies-with-poetry)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:376 +msgid "This is hidden. TO" +msgstr "" + +#: ../../package-structure-code/intro.md:179 +msgid "Intro" +msgstr "" + +#: ../../package-structure-code/intro.md:179 +msgid "Python package structure" +msgstr "" + +#: ../../package-structure-code/intro.md:179 +msgid "pyproject.toml Package Metadata" +msgstr "" + +#: ../../package-structure-code/intro.md:179 +msgid "Build Your Package" +msgstr "" + +#: ../../package-structure-code/intro.md:179 +msgid "Declare dependencies" +msgstr "" + +#: ../../package-structure-code/intro.md:179 +msgid "Package Build Tools" +msgstr "" + +#: ../../package-structure-code/intro.md:179 +msgid "Complex Builds" +msgstr "" + +#: ../../package-structure-code/intro.md:179 +msgid "Create & Build Your Package" +msgstr "" + +#: ../../package-structure-code/intro.md:193 +msgid "Publish with Conda / PyPI" +msgstr "" + +#: ../../package-structure-code/intro.md:193 +msgid "Package versions" +msgstr "" + +#: ../../package-structure-code/intro.md:193 +msgid "Code style" +msgstr "" + +#: ../../package-structure-code/intro.md:193 +msgid "Publish your package" +msgstr "" + +#: ../../package-structure-code/intro.md:1 +msgid "Python Package Structure" +msgstr "" + +#: ../../package-structure-code/intro.md:3 +msgid "This section provides guidance on your Python package's structure, code format, and style. It also reviews the various [packaging tools](python-package-build-tools) you can use to [build](python-package-distribution-files-sdist-wheel) and [publish](publish-python-package-pypi-conda) your Python package." +msgstr "" + +#: ../../package-structure-code/intro.md:7 +msgid "If you want end-to-end tutorials, check out our tutorial series that starts by introducing [what a Python package is](what-is-a-package)." +msgstr "" + +#: ../../package-structure-code/intro.md:9 +msgid "If you are confused by Python packaging, you are not alone! The good news is that some great modern packaging tools ensure you follow best practices. Here, we review tool features and suggest tools you can use for your Python packaging workflow." +msgstr "" + +#: ../../package-structure-code/intro.md:14 +msgid "Checkout our beginning-to-end create a Python package tutorials" +msgstr "" + +#: ../../package-structure-code/intro.md:23 +msgid "How this content is developed" +msgstr "" + +#: ../../package-structure-code/intro.md:24 +msgid "All of the content in this guide has been vetted by community members, including maintainers and developers of the core packaging tools." +msgstr "" + +#: ../../package-structure-code/intro.md:35 +msgid "✨ 1. Package file structure ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:39 +msgid "src layout, flat layout and where should tests folders live? No matter what your level of packaging knowledge is, this page will help you decide upon a package structure that follows modern python best practices." +msgstr "" + +#: ../../package-structure-code/intro.md:44 +msgid "✨ 2. Learn about building your package ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:48 +msgid "To publish your Python package on PyPI, you will need to first build it. The act of \"building\" refers to the process of placing your package code and metadata into a format that can be published on PyPI. Learn more about building your Python package." +msgstr "" + +#: ../../package-structure-code/intro.md:57 +msgid "✨ 4. Add metadata ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:61 +msgid "Learn how to add project metadata to your Python package to support both filtering on PyPI and also the metadata that a package installer needs to build and install your package." +msgstr "" + +#: ../../package-structure-code/intro.md:68 +msgid "✨ 3. What Python package tool should you use? ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:72 +msgid "Learn more about the suite of packaging tools out there. And learn which tool might be best for you." +msgstr "" + +#: ../../package-structure-code/intro.md:78 +msgid "✨ 4. Publish to PyPI and Conda ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:82 +msgid "If you have a pure Python package, it's a straight forward process to publish to both PyPI and then a Conda channel such as conda-forge. Learn more here." +msgstr "" + +#: ../../package-structure-code/intro.md:89 +msgid "✨ 5. Setup package versioning ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:93 +msgid "Semver (numeric versioning) and Calver (versioning using the date) are 2 common ways to version a package. Which one should you pick? Learn more here." +msgstr "" + +#: ../../package-structure-code/intro.md:99 +msgid "✨ 6. Code style & linters ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:103 +msgid "Black, blue, flake8, Ruff - which tools can help you ensure your package follows best practices for code format? Learn more about the options and why this is important here." +msgstr "" + +#: ../../package-structure-code/intro.md:111 +msgid "Figure showing a decision tree with the various packaging tool front-end and back-end options." +msgstr "" + +#: ../../package-structure-code/intro.md:113 +msgid "Diagram showing the various front-end build tools that you can select from. See the packaging tools page to learn more about each tool." +msgstr "" + +#: ../../package-structure-code/intro.md:118 +msgid "If you are considering submitting a package for peer review, have a look at the bare-minimum [editor checks](https://www.pyopensci.org/software-peer-review/how-to/editor-in-chief-guide.html#editor-checklist-template) that pyOpenSci performs before a review begins. These checks are useful to explore for both authors planning to submit a package to us for review and for anyone who is just getting started with creating a Python package." +msgstr "" + +#: ../../package-structure-code/intro.md:125 +msgid "What you will learn here" +msgstr "" + +#: ../../package-structure-code/intro.md:127 +msgid "In this section of our Python packaging guide, we:" +msgstr "" + +#: ../../package-structure-code/intro.md:129 +msgid "Provide an overview of the options available to you when packaging your code." +msgstr "" + +#: ../../package-structure-code/intro.md:131 +msgid "Suggest tools and approaches that both meet your needs and also support existing standards." +msgstr "" + +#: ../../package-structure-code/intro.md:133 +msgid "Suggest tools and approaches that will allow you to expand upon a workflow that may begin as a pure Python code and evolve into code that requires addition layers of complexity in the packaging build." +msgstr "" + +#: ../../package-structure-code/intro.md:136 +msgid "Align our suggestions with the most current, accepted [PEPs (Python Enhancement Protocols)](https://peps.python.org/pep-0000/) and the [Scientific Python community SPECs](https://scientific-python.org/specs/)." +msgstr "" + +#: ../../package-structure-code/intro.md:139 +msgid "In an effort to maintain consistency within our community, we also align with existing best practices being implemented by developers of core Scientific Python packages such as Numpy, SciPy and others." +msgstr "" + +#: ../../package-structure-code/intro.md:143 +msgid "Guidelines for pyOpenSci's packaging recommendations" +msgstr "" + +#: ../../package-structure-code/intro.md:145 +msgid "The flexibility of the Python programming language lends itself to a diverse range of tool options for creating a Python package. Python is so flexible that it is one of the few languages that can be used to wrap around other languages. The ability of Python to wrap other languages is one the reasons you will often hear Python described as a [\"glue\" language](https://numpy.org/doc/stable/user/c-info.python-as-glue.html)\"" +msgstr "" + +#: ../../package-structure-code/intro.md:151 +msgid "If you are building a pure Python package, then your packaging setup can be simple. However, some scientific packages have complex requirements as they may need to support extensions or tools written in other languages such as C or C++." +msgstr "" + +#: ../../package-structure-code/intro.md:155 +msgid "To support the many different uses of Python, there are many ways to create a Python package. In this guide, we suggest packaging approaches and tools based on:" +msgstr "" + +#: ../../package-structure-code/intro.md:158 +msgid "What we think will be best and easiest to adopt for those who are newer to packaging." +msgstr "" + +#: ../../package-structure-code/intro.md:160 +msgid "Tools that we think are well maintained and documented." +msgstr "" + +#: ../../package-structure-code/intro.md:161 +msgid "A shared goal of standardizing packaging approaches across this (scientific) Python ecosystem." +msgstr "" + +#: ../../package-structure-code/intro.md:164 +msgid "Here, we also try to align our suggestions with the most current, accepted [Python community](https://packaging.python.org/en/latest/) and [scientific community](https://scientific-python.org/specs/)." +msgstr "" + +#: ../../package-structure-code/intro.md:167 +msgid "Suggestions in this guide are not pyOpenSci review requirements" +msgstr "" + +#: ../../package-structure-code/intro.md:170 +msgid "The suggestions for package layout in this section are made with the intent of being helpful; they are not specific requirements for your package to be reviewed and accepted into our pyOpenSci open source ecosystem." +msgstr "" + +#: ../../package-structure-code/intro.md:174 +msgid "Please check out our [package scope page](https://www.pyopensci.org/software-peer-review/about/package-scope.html) and [review requirements in our author guide](https://www.pyopensci.org/software-peer-review/how-to/author-guide.html#) if you are looking for pyOpenSci's Python package review requirements!" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:1 +msgid "Publishing Your Package In A Community Repository: PyPI or Anaconda.org" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:5 +msgid "pyOpenSci requires that your package has an distribution that can be installed from a public community repository such as PyPI or a conda channel such as `bioconda` or `conda-forge` on Anaconda.org." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:9 +msgid "Below you will learn more about the various publishing options for your Python package." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:14 +msgid "Installing packages in the same environment using both pip and conda can lead to package conflicts." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:16 +msgid "To minimize conflicts for users who may be using conda (or pip) to manage local environments, consider publishing your package to both PyPI and the conda-forge channel on Anaconda.org." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:18 +msgid "Below you will learn more specifics about the differences between PyPI and conda publishing of your Python package." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:24 +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:6 +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 "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:26 +msgid "Once you have published both package distributions (the source distribution and the wheel) to PyPI, you can then publish to conda-forge. The 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 "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:29 +msgid "What is PyPI" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:31 +msgid "[PyPI](https://pypi.org/) is an online Python package repository that you can use to both find and install and publish your Python package. There is also a test PyPI repository where you can test publishing your package prior to the final publication on PyPI." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:36 +msgid "Many if not most Python packages can be found on PyPI and are thus installable using `pip`." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:38 +msgid "The biggest different between using pip and conda to install a package is that conda can install any package regardless of the language(s) that it is written in. Whereas `pip` can only install Python packages." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:43 +msgid "Click here for a tutorial on publishing your package to PyPI." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:52 +msgid "On the package build page, we discussed the [two package distribution types that you will create when making a Python package](python-package-distribution-files-sdist-wheel): SDist (packaged as a .tar.gz or .zip) and Wheel (.whl) which is really a zip file. Both of those file \"bundles\" will be published on PyPI when you use [a standard build tool](python-package-build-tools) to build your package." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:60 +msgid "What is conda and Anaconda.org?" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:62 +msgid "conda is an open source package and environment management tool. conda can be used to install tools from the [Anaconda repository](https://repo.anaconda.com/)." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:66 +msgid "Anaconda.org contains public and private repositories for packages. These repositories are known as channels (discussed below)." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:69 +msgid "A brief history of conda's evolution" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:72 +msgid "The conda ecosystem evolved years ago to provide support for, and simplify the process of, managing software dependencies in scientific Python projects." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:76 +msgid "Many of the core scientific Python projects depend upon or wrap around tools and extensions that are written in other languages, such as C++. In the early stages of the scientific ecosystem's development, these non-Python extensions and tools were not well supported on PyPI, making publication difficult. In recent years there is more support for complex builds that allow developers to bundle non-Python code into a Python distribution using the [wheel distribution format](python-wheel)." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:78 +msgid "Conda provides a mechanism to manage these dependencies and ensure that the required packages are installed correctly." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:82 +msgid "While conda was originally created to support Python packages, it is now used across all languages. This cross-language support makes it easier for some packages to include and have access to tools written in other languages, such as C/C++ (gdal), Julia, or R. Creating an environment that mixes all of these packages is usually easier and more consistent with full-fledged package managers like conda." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:90 +msgid "conda channels" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:92 +msgid "conda built packages are housed within repositories that are called channels. The conda package manager can install packages from different channels." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:95 +msgid "There are several core public channels that most people use to install packages using conda, including:" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:98 +msgid "**defaults:** this is a channel managed by Anaconda. It is the version of the Python packages that you will install if you install the Anaconda Distribution. Anaconda (the company) decides what packages live on the `defaults` channel." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:99 +msgid "[**conda-forge:**](https://conda-forge.org/) this is a community-driven channel that focuses on scientific packages. This channel is ideal for tools that support geospatial data. Anyone can publish a package to this channel." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:100 +msgid "[**bioconda**](https://bioconda.github.io/): this channel focuses on biomedical tools." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:102 +msgid "**conda-forge** emerged as many of the scientific packages did not exist in the `defaults` Anaconda channel." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:107 +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 "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:109 +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 "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:113 +msgid "conda channels, PyPI, conda, pip - Where to publish your package" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:115 +msgid "You might be wondering why there are different package repositories that can be used to install Python packages." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:118 +msgid "And more importantly you are likely wondering how to pick the right repository to publish your Python package." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:121 +msgid "The answer to both questions relates dependency conflicts." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:125 +msgid "Image showing an XKCD comic that shows a web of Python environments and tools and installations. At the bottom is says - My python environment has become so degraded that my laptop has been declared a superfund site." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:127 +msgid "Installing Python and Python packages from different repositories can lead to environment conflicts where a version of on package doesn't work with a version of another package. To keep your environments clean and working, it's best to install packages from the same repository. So use pip to install everything. Or use conda. If you can, try to avoid installing package from both pip and conda into the same environment." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:135 +msgid "Managing Python package dependency conflicts" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:137 +msgid "Python environments can encounter conflicts because Python tools can be installed from different repositories. Broadly speaking, Python environments have a smaller chance of dependency conflicts when the tools are installed from the same package repository. Thus environments that contain packages installed from both pip and conda are more likely to yield dependency conflicts." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:144 +msgid "Similarly installing packages from the default anaconda channel mixed with the conda-forge channel can also lead to dependency conflicts." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:146 +msgid "Many install packages directly from conda `defaults` channel. However, because this channel is managed by Anaconda, the packages available on it are limited to those that Anaconda decides should be core to a stable installation. The conda-forge channel was created to complement the `defaults` channel. It allows anyone to submit a package to be published in the channel . Thus, `conda-forge` channel ensures that a broad suite of user-developed community packages can be installed from conda." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:150 +msgid "Take-aways: If you can, publish on both PyPI and conda-forge to accommodate more users of your package" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:152 +msgid "The take-away here for maintainers is that if you anticipate users wanting to use conda to manage their local environments (which many do), you should consider publishing to both PyPI and the conda-forge channel (_more on that below_)." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:157 +msgid "Additional resources" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:158 +msgid "[learn more about why conda-forge was created, here](https://conda-forge.org/docs/user/introduction.html)" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:160 +msgid "[To learn more about conda terminology, check out their glossary.](https://docs.conda.io/projects/conda/en/latest/glossary.html )" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:165 +msgid "How to submit to conda-forge" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:167 +msgid "While pyOpenSci doesn't require you to add your package to conda-forge, we encourage you to consider doing so!" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:170 +msgid "Once your package is on PyPI, the process to add your package to conda-forge is straight forward to do. [You can follow the detailed steps provided by the conda-forge maintainer team.](https://conda-forge.org/docs/maintainer/adding_pkgs.html)." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:175 +msgid "Click here for a tutorial on adding your package to conda-forge." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:182 +msgid "If you want a step by step tutorial, click here." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:185 +msgid "Once your package is added, you will have a feedstock repository on GitHub with your packages name" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:188 +msgid "[Here is an example conda-forge feedstock for the pyOpenSci approved package - movingpandas](https://github.com/conda-forge/movingpandas-feedstock)" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:191 +msgid "Maintaining your conda-forge package repository" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:193 +msgid "Once your package is on the conda-forge channel, maintaining it is simple. Every time that you push a new version of your package to PyPI, it will kick off a continuous integration build that updates your package in the conda-forge repository. Once that build is complete, you will get a notification to review the update." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:199 +msgid "You can merge the pull request for that update once you are happy with it. A ready-to-merge PR usually means ensuring that your project's dependencies (known as runtime requirements) listed in the updated YAML file found in the pull request match the PyPI metadata of the new release." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:1 +msgid "Use a pyproject.toml file for your package configuration & metadata" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:10 +msgid "Important pyproject.toml take aways" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:14 +msgid "There are only two tables that are required for an installable Python package: **[build-system]** and **[project]**. The **[project]** table stores your package's metadata." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:15 +msgid "There are only two _required_ fields in the **[project]** table: **name=** and **version=**." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:16 +msgid "We suggest you add additional metadata to your `pyproject.toml` file as it will make it easier for users to find your project on PyPI." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:17 +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 your package or publish to PyPI." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:18 +msgid "There is no specific order for tables in the `pyproject.toml` file. However fields need to be placed within the correct table sections. For example `requires =` always need to be associated with the **[build-system]** table." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:19 +msgid "**python-requires**: is important to have in your `pyproject.toml` file as it helps pip install your package." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:24 +msgid "when these are published, remove this todo" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:33 +msgid "Need help creating your pyproject.toml file? This tutorial will walk you through the process." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:47 +msgid "Click here if need help migrating from setup.py/setup.cfg to pyproject.toml" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:57 +msgid "About the pyproject.toml file" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:59 +msgid "Every modern Python package should include a `pyproject.toml` file. If your project is pure Python and you're using a `setup.py` or `setup.cfg` file to describe its metadata, you should consider migrating your metadata and build information to a `pyproject.toml` file." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:61 +msgid "If your project isn’t pure-python, you might still require a `setup.py` file to build the non Python extensions. However, a `pyproject.toml` file should still be used to store your project’s metadata." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:63 +msgid "What happened to setup.py & how do i migrate to pyproject.toml?" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:65 +msgid "Prior to August 2017, Python package metadata was stored either in the `setup.py` file or a `setup.cfg` file. In recent years, there has been a shift to storing Python package metadata in a much more user-readable `pyproject.toml` format. Having all metadata in a single file:" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:67 +msgid "simplifies package management," +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:68 +msgid "allows you to use a suite of different [build backends](https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-build-tools.html#build-back-ends) such as (flit-core, hatchling, pdm-build), and" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:69 +msgid "aligns with modern best practices." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:76 +msgid "The standard file that Python packages use to [specify build requirements and metadata is called a **pyproject.toml**](https://packaging.python.org/en/latest/specifications/declaring-project-metadata/). Adding metadata, build requirements and package dependencies to a **pyproject.toml** file replaces storing that information in a setup.py or setup.cfg file." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:81 +msgid "About the .toml format" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:83 +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 founded on key/value pairs. Each section in the **pyproject.toml** file contains a `[table identifier]`. Below that table identifier are key/value pairs that support configuration for that particular table." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:87 +msgid "Below `[build-system]` is considered a table in the toml language." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:88 +msgid "Within the `build-system` table below `requires =` is a key." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:89 +msgid "The associated value for `requires` is an array containing the value `\"hatchling\"`." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:97 +msgid "How the pyproject.toml is used when you build a package" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:101 +msgid "When you publish to PyPI, you will notice that each package has metadata listed. Let’s have a look at [xclim](https://pypi.org/project/xclim/), one of our [pyOpenSci packages](https://www.pyopensci.org/python-packages.html). Notice that on the PyPI landing page you see some metadata about the package including python, maintainer information and more. PyPI is able to populate this metadata because it was defined using correct syntax and classifiers by Xclim's maintainers, [pyproject.toml file](https://github.com/Ouranosinc/xclim/blob/master/pyproject.toml). This metadata when the xclim package is built, is translated into a distribution file that allows PyPI to read the metadata and print it out on their website." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:103 +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:83 +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 "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:108 +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:88 +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 "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:113 +msgid "Benefits of using a pyproject.toml file" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:115 +msgid "Including your package's metadata in a separate human-readable **pyproject.toml** format also allows someone to view the project's metadata in a GitHub repository." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:123 +msgid "Setup.py is still useful for complex package builds" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:127 +msgid "Using **setup.py** to manage package builds and metadata [can cause problems with package development](https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html). In some cases where a Python package build is complex, a **setup.py** file may be required. While this guide will not cover complex builds, we will provide resources working with complex builds in the future." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:133 +msgid "Optional vs. Required pyproject.toml file fields" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:135 +msgid "When you create your `pyproject.toml` file, there are numerous metadata fields that you can use. Below we suggest specific fields to get you started that support publication on PyPI and users finding your package." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:137 +msgid "[An overview of all of the project metadata elements can be found here.](https://packaging.python.org/en/latest/specifications/core-metadata/#project-url-multiple-use)" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:139 +msgid "Required fields for the `[project]` table" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:141 +msgid "As mentioned above, your `pyproject.toml` file needs to have a **`name`** and **`version`** field in order to properly build your package:" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:143 +msgid "`name`: This is the name of your project provided as a string" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:144 +msgid "`version`: This is the version of your project. If you are using a SCM tool for versioning (using git tags to determine versions), then the version may be dynamic (more on that below)." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:146 +msgid "Optional fields to include in the `[project]` table" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:148 +msgid "We strongly suggest that you also add the metadata keys below as they will help users finding your package on PyPI. These fields will make it clear how your package is structured, what platforms you support and what dependencies your package requires." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:153 +msgid "**Description:** this is a short one-line description of your package." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:154 +msgid "**Readme:** A link to your README.md file is used for the long long-description. This information will be published on your packages PyPI landing page." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:155 +msgid "**Requires-python** (used by pip): this is a field that is used by pip. Here you tell the installer whether you are using Python 2.x or 3.x. Most projects will be using 3.x." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:156 +msgid "**License:** the license you are using" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:157 +msgid "**Authors:** these are the original authors of the package. Sometimes the authors are different from the maintainers. Other times they might be the same." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:158 +msgid "**Maintainers:** you can choose to populate this or not. You can populate this using a list with a sub element for each author or maintainer name, email" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:166 +msgid "**dependencies:** dependencies are optional but we strongly suggest you include them in your pyproject.toml. Dependencies will be installed by pip when your project is installed creating a better user-experience." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:168 +msgid "**`[project.optional-dependencies]`:** the optional or development dependencies will be installed if someone runs `python -m pip install projectname[dev]`. This is a nice way to include your development dependencies for users who may wish to contribute to your project." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:170 +msgid "**keywords:** These are the keywords that will appear on your PyPI landing page. Think of them as words that people might use to search for your package." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:171 +msgid "**classifiers:** The classifiers section of your metadata is also important for the landing page of your package in PyPI and for filtering of packages in PyPI. A list of [all options for classifiers can be found her](https://PyPI.org/classifiers/)e. Some of the classifiers that you should consider including" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:172 +msgid "Development Status" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:173 +msgid "Intended Audience" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:174 +msgid "Topic" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:175 +msgid "License" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:176 +msgid "Programming language" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:178 +msgid "Advanced options in the pyproject.toml file" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:180 +msgid "The examples at the bottom of this page contain ..." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:182 +msgid "**`[project.scripts]` (Entry points):** Entry points are optional. If you have a command line tool that runs a specific script hosted in your package, you may include an entry point to call that script directly at the command line (rather than at the Python shell)." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:184 +msgid "Here is an example of[a package that has entry point script](https://github.com/pyOpenSci/pyosMeta/blob/main/pyproject.toml#L60)s. Notice that there are several core scripts defined in that package that perform sets of tasks. The pyOpenSci is using those scripts to process their metadata." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:185 +msgid "**Dynamic Fields:** if you have fields that are dynamically populated. One example of this is if you are using scm / version control based version with tools like `setuptooms_scm`, then you might use the dynamic field, such as version (using scm) **dynamic = [\"version\"]**" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:187 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Add dependencies to your pyproject.toml file" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:189 +msgid "The pyproject.toml file can also be used as a replacement for the requirements.txt file which has been traditionally used to store development dependencies such as pytest, code formatters such as Black and documentation tools such as sphinx." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:191 +msgid "To add dependencies to your build, add a `[project.optional-dependencies]` table to your pyproject.toml file." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:193 +msgid "Then specify dependency groups as follows:" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:200 +msgid "Following the above example, you install dependencies like this:" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:202 +msgid "`python -m pip install -e .[tests]`" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:204 +msgid "The above will install both your package in editable mode and all of the dependencies declared in the tests section of your `[project.optional-dependencies]` table." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:206 +msgid "To install all dependencies and also your package, you'd use:" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:208 +msgid "`python -m pip install -e .[tests,lint,docs]`" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:210 +msgid "Recursive dependencies" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:214 +msgid "You can also setup sets of recursive dependencies. [See this blog post for more.](https://hynek.me/articles/python-recursive-optional-dependencies/)" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:217 +msgid "Example pyproject.toml for building using hatchling" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:219 +msgid "Below is an example build configuration for a Python project. This example package setup uses **hatchling** to build the [package's sdist and wheels](python-package-distribution-files-sdist-wheel)." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:227 +msgid "Notice that dependencies are specified in this file." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:229 +msgid "Example pyproject.toml for building using setuptools" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:231 +msgid "The package metadata including authors, keywords, etc is also easy to read. Below you can see the same TOML file that uses a different build system (setuptools). Notice how simple it is to swap out the tools needed to build this package!" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:235 +msgid "In this example package setup you use:" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:237 +msgid "**setuptools** to build the [package's sdist and wheels](python-package-distribution-files-sdist-wheel)" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:238 +msgid "**setuptools_scm** to manage package version updates using version control tags" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:240 +msgid "In the example below `[build-system]` is the first table of values. It has two keys that specify the build backend API and containing package:" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:243 +msgid "`requires =`" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:244 +msgid "`build-back-end =`" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:251 +msgid "[Click here to read about our packaging build tools including PDM, setuptools, Poetry and Hatch.](/package-structure-code/python-package-build-tools)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:1 +msgid "Python Packaging Tools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:3 +msgid "Tools for building your package" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:5 +msgid "There are a several different build tools that you can use to [create your Python package's _sdist_ and _wheel_ distributions](python-package-distribution-files-sdist-wheel). Below, we discuss the features, benefits and limitations of the most commonly used Python packaging tools. We focus on pure-python packages in this guide. However, we also highlight tools that currently support packages with C/C++ and other language extensions." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:13 +msgid "Decision tree diagram showing the various front and back end packaging tools. You can decide what packaging tool to use by thinking about what features you need. PDM and Hatch are currently the most flexible tools as they also using different build back-ends. As such currently PDM and Hatch are the tools we think beginners might appreciate most with Poetry being a close second. Poetry is nice for pure Python projects." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:15 +msgid "Diagram showing the different front end build tools available to use in the Python package ecosystem that you can select from. We selected tools to include in this diagram based upon the PyPI survey which helped us understand the most populate tools in the ecosystem. Each tool has different features as highlighted below." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:18 +msgid "If you want to know more about Python packages that have extensions written in other languages, [check out the page on complex package builds.](complex-python-package-builds)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:21 +msgid "Tools that we review here" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:23 +msgid "In this section we have selected tools that were returned as the most popular packaging tools in the PyPA survey. You will learn more about the following tools on this page:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:27 +msgid "[Twine](https://twine.readthedocs.io/en/stable/), [Build](https://pypa-build.readthedocs.io/en/stable/) + [setuptools](https://setuptools.pypa.io/en/latest/)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:28 +msgid "[Flit](https://flit.pypa.io/en/stable/)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:29 +msgid "[Hatch](https://hatch.pypa.io/latest/)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:30 +msgid "[PDM](https://pdm.fming.dev/latest/)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:31 +msgid "[Poetry](https://python-poetry.org/docs/)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:33 +msgid "Summary of tools Hatch vs. PDM vs. Poetry (and setuptools)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:35 +msgid "If you are looking for a quick summary, read below." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:37 +msgid "In general, any modern tool that you select from this page will be great to build your package. Selecting a tool comes down to the features that you are looking for in your workflow." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:38 +msgid "We suggest that beginners start with a modern workflow tool like PDM as opposed to navigating the complexities of setuptools." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:39 +msgid "If you are going to use Poetry (it is the most popular tool and does have the best documentation) beware of the upper bounds dependency additions and consider overriding dependencies when you add them. If you do that Poetry will work well for pure-python builds! Poetry also has an active discord where you can ask questions." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:41 +msgid "Below are some features that Hatch and PDM offer that Poetry does not." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:43 +msgid "PDM:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:45 +msgid "Supports other back-ends making it ideal for builds that are not pure Python. This means PDM is a great option for both pure python and more complex Python builds as it supports meson-python and other build backends." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:46 +msgid "Offers flexibility in dependency management which we like" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:47 +msgid "Offers lock files if you need them" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:49 +msgid "Hatch:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:51 +msgid "Offers matrix environment management that allows you to run tests across Python versions. If this feature is important to you, then Hatch is a clear winner." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:52 +msgid "Offers a Nox / Make file like tool to streamline your build workflow. If you are looking to reduce the number of tools in your workflow, Hatch might be for you." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:55 +msgid "Build front-end vs. build back-end tools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:57 +msgid "To better understand your options, when it comes to building a Python package, it's important to first understand the difference between a build tool front-end and build back-end." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:62 +msgid "Build back-ends" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:64 +msgid "Most packaging tools have a back-end build tool that builds you package and creates associated [(sdist and wheel) distribution files](python-package-distribution-files-sdist-wheel). Some tools, such as **Flit**, only support pure-Python package builds. A pure-Python build refers to a package build that does not have extensions that are written in another programming language (such as `C` or `C++`)." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:71 +msgid "Other packages that have C and C++ extensions (or that wrap other languages such as fortran) require additional code compilation steps when built. Back-ends such as **setuptools.build**, **meson.build** and **scikit-build** support complex builds with custom steps. If your build is particularly complex (i.e. you have more than a few `C`/`C++` extensions), then we suggest you use **meson.build** or **scikit-build**." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:77 +msgid "Python package build front-ends" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:79 +msgid "A packaging front-end tool refers to a tool that makes it easier for you to perform common packaging tasks using similar commands. These tasks include:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:82 +msgid "[Build your packages (create the sdist and wheel distributions)](python-package-distribution-files-sdist-wheel)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:83 +msgid "Installing your package in a development mode (so it updates when you update your code)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:84 +msgid "Publishing to PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:85 +msgid "Running tests" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:86 +msgid "Building documentation" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:87 +msgid "Managing an environment or multiple environments in which you need to run tests and develop your package" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:89 +msgid "There are several Python packaging tools that you can use for pure Python builds. Each front-end tool discussed below supports a slightly different set of Python packaging tasks." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:93 +msgid "For instance, you can use the packaging tools **Flit**, **Hatch** or **PDM** to both build and publish your package to PyPI. However while **Hatch** and **PDM** support versioning and environment management, **Flit** does not. If you want a tool that supports dependency locking, you can use **PDM** or **Poetry** but not **Hatch**. If you only need to build your package's sdist and wheel distribution files, then you can stick with PyPA's Build. You'd then use Twine to publish to PyPI." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:100 +msgid "If you are using **Setuptools**, there is no default user-friendly build front-end that performs multiple tasks. You will need to use **build** to build your package and **twine** to publish to PyPI." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:103 +msgid "Example build steps that can be simplified using a front-end tool" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:105 +msgid "Below, you can see how a build tool streamlines your packaging experience. Example to build your package with **Hatch**:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:115 +msgid "Example build steps using the **setuptools** back-end and **build**:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:125 +msgid "Choosing a build back-end" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:127 +msgid "Most front-end packaging tools have their own back-end build tool. The build tool creates your package's (sdist and wheel) distribution files. For pure Python packages, the main difference between the different build back-ends discussed below is:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:132 +msgid "How configurable they are - for example, do they allow you to add build steps that support non python extensions?" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:133 +msgid "How much you need to configure them to ensure the correct files are included in your sdist and wheel distributions." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:135 +msgid "Build back-end support for non pure-python packages" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:137 +msgid "It is important to note that some build back-ends, such as **Flit-core**, only support pure Python builds. Other back-ends support C and C++ extensions as follows:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:140 +msgid "setuptools supports builds using C / C++ extensions" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:141 +msgid "Hatchling (hatch's back-end) supports C / C++ extensions via plugins that the developer creates to customize a build" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:142 +msgid "PDM's back-end supports C / C++ extensions by using setuptools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:143 +msgid "Poetry's back-end supports C/C++ extensions however this functionality is currently undocumented. As such we don't recommend using Poetry for complex or non pure Python builds until it is documented." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:145 +msgid "While we won't discuss more complex builds below, we will identify which tools have documented support for C / C++ extensions." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:148 +msgid "An ecosystem of Python build tools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:150 +msgid "Below we introduce several of the most commonly used Python packaging build front-end tools. We highlight the features that each tool offers as a way to help you decide what tool might be best for your workflow." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:154 +msgid "We do not suggest using setuptools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:157 +msgid "We suggest that you pick one of the modern tools listed above rather than setuptools because setuptools will require some additional knowledge to set up correctly." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:161 +msgid "We review setuptools as a back-end because it is still popular. However it is not the most user friendly option." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:165 +msgid "The most commonly used tools in the ecosystem are setuptools back-end (with build) and Poetry (a front end tool with numerous features and excellent documentation)." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:171 +msgid "Graph showing the results of the 2022 PyPA survey of Python packaging tools. On the x axis is percent response and on the y axis are the tools." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:173 +msgid "The Python developers survey results (n=>8,000 PyPI users) show setuptools and poetry as the most commonly used Python packaging tools. The core tools that we've seen being used in the scientific community are included here. [You can view the full survey results by clicking here.](https://drive.google.com/file/d/1U5d5SiXLVkzDpS0i1dJIA4Hu5Qg704T9/view) NOTE: this data represent maintainers across domains and is likely heavily represented by those in web development. So this represents a snapshot across the broader Python ecosystem." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:176 +msgid "Chose a build workflow tool" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:178 +msgid "The tools that we review below include:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:180 +msgid "Twine, Build + setuptools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:181 +#: ../../package-structure-code/python-package-build-tools.md:291 +msgid "Flit" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:182 +#: ../../package-structure-code/python-package-build-tools.md:331 +msgid "Hatch" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:183 +#: ../../package-structure-code/python-package-build-tools.md:215 +#: ../../package-structure-code/python-package-build-tools.md:230 +msgid "PDM" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:184 +#: ../../package-structure-code/python-package-build-tools.md:374 +msgid "Poetry" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:186 +msgid "When you are selecting a tool, you might consider this general workflow of questions:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:189 +msgid "**Is your tool pure python? Yes?** You can use any tool that you wish! Pick the tool that has the features that you want to use in your build workflow. We suggest:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:191 +msgid "Flit, Hatch, PDM or Poetry (read below for more)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:193 +msgid "**Does your tool have a few C or C++ extensions?** Great, we suggest using **PDM** for the time being. It is the only tool in the list below that has both documented workflow to support such extensions and support for other back-ends in the case that build hooks are not enough for your workflow. PDM supports other back-ends such as scikit-build and meson-python that will allow you to fully customize your package's build." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:197 +msgid "NOTE: You can also use Hatch for non pure python builds. Hatch, similar to PDM, allows you to write your own build hooks or plugins to support custom build steps. But currently, hatch does not support other build back ends. Many of the core scientific packages are moving to meson-python to build their packages. Thus, we appreciate that PDM can work with meson-python specifically." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:199 +msgid "Python packaging tools summary" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:201 +msgid "Below, we summarize features offered by the most popular build front end tools. It is important to keep in mind that these front-end tools remove the need to use other core tools in your workflow. For example if you use setuptools, you will need to also use Build and Twine to build your package and publish to PyPI. But if you use Poetry, Hatch or PDM you can do all of those things using the same tool (e.g. `hatch build`, `hatch publish` or `pdm build`, `pdm publish`)." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:204 +msgid "Note that because setuptools does not offer a front-end interface, it is not included in the table." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:208 +msgid "Package tool features table" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +msgid "Feature, Flit, Hatch, PDM, Poetry" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +msgid "Default Build Back-end" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +msgid "Flit-core" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +msgid "hatchling" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +msgid "Poetry-core" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +#: ../../package-structure-code/python-package-build-tools.md:251 +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Use Other Build Backends" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "✖" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +#: ../../package-structure-code/python-package-build-tools.md:251 +#: ../../package-structure-code/python-package-build-tools.md:304 +#: ../../package-structure-code/python-package-build-tools.md:348 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "✅" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Dependency management" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "Publish to PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +msgid "Version Control based versioning (using `git tags`)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +#: ../../package-structure-code/python-package-build-tools.md:251 +#: ../../package-structure-code/python-package-build-tools.md:348 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Version bumping" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Environment Management" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +msgid "More than one maintainer? (bus factor)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:225 +msgid "Notes:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:227 +msgid "_Hatch plans to support dependency management in the future_" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:228 +msgid "Poetry supports semantic versioning. Thus, it will support version bumping following commit messages if you use a tool such as Python Semantic Release" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:232 +msgid "[PDM is a Python packaging and dependency management tool](https://pdm.fming.dev/latest/). PDM supports builds for pure Python projects. It also provides multiple layers of support for projects that have C and C++ extensions." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:236 +msgid "PDM support for C and C++ extensions" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:238 +msgid "PDM supports using the PDM-back-end and setuptools at the same time. This means that you can run setuptools to compile and build C extensions. PDM's build back-end receives the compiled extension files (.so, .pyd) and packages them with the pure Python files." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:244 +msgid "PDM Features" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "Feature, PDM, Notes" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "When you setup PDM it allows you to select one of several build back ends including: PDM-core, flit-core and hatchling. PDM also can work with Meson-Python which supports move complex python builds." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "Dependency specifications" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "PDM has flexible support for managing dependencies. PDM defaults to using an open bound (e.g. `requests >=1.2`) approach to dependencies. However you can [customize how you want to add dependencies in case you prefer another approach such as that of Poetry which uses an upper bound limit](https://pdm.fming.dev/latest/usage/dependency/#about-update-strategy).**" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "Environment lock files" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "PDM and Poetry are currently the only tools that create environment lock files. Lock files are often most useful to developers creating web apps where locking the environment is critical for consistent user experience. For community-used packages, you will likely never want to use a lock file." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Environment management" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "PDM provides environment management support. It supports Python virtual environments, conda and a local `__pypackages__` environment which is a newer option in the Python ecosystem. No extensions are needed for this support." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "Select your environment type on install" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "When you run `PDM init`, PDM will discover environments that are already on your system and allow you to select one to use for your project." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "PDM supports publishing to both test PyPI and PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +#: ../../package-structure-code/python-package-build-tools.md:348 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Version Control based versioning" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "PDM has a setuptools_scm like tool built into it which allows you to use dynamic versioning that rely on git tags." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "PDM supports you bumping the version of your package using standard semantic version terms patch; minor; major" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +#: ../../package-structure-code/python-package-build-tools.md:304 +#: ../../package-structure-code/python-package-build-tools.md:348 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Follows current packaging standards" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "PDM supports current packaging standards for adding metadata to the **pyproject.toml** file." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +#: ../../package-structure-code/python-package-build-tools.md:304 +#: ../../package-structure-code/python-package-build-tools.md:348 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Install your package in editable mode" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "PDM supports installing your package in editable mode." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +#: ../../package-structure-code/python-package-build-tools.md:304 +#: ../../package-structure-code/python-package-build-tools.md:348 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Build your sdist and wheel distributions" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "Similar to all of the other tools PDM builds your packages sdist and wheel files for you." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:264 +msgid "PDM vs. Poetry" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:265 +msgid "The functionality of PDM is similar to Poetry. However, PDM also offers additional, documented support for C extensions and version control based versioning. As such, PDM is preferred for those working on non pure-Python packages." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:269 +msgid "If you are deciding between the Poetry and PDM, a smaller difference is the default way that dependencies are added to your pyproject.toml file." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:271 +msgid "Poetry by default follows strict semantic versioning adding dependencies to your pyproject.toml file [using an upper bounds constraint (`^`)](https://python-poetry.org/docs/dependency-specification/#version-constraints). Upper bounds lock means that Poetry will never bump a dependency to the next major version (i.e. from 1.2 to 2.0). However, you can tell Poetry to use an open bound approach by explicitly adding the package like this: `poetry add requests >= 1.2` rather than just using `poetry add requests` which will result in a upper bound locked (ie Upper bound locks means that requests 2.0 could never be installed even if it came out and your package could benefit from it)." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:272 +msgid "PDM defaults to open-bounds (`>=`) dependency additions which is the preferred approach in the scientific python ecosystem. However, PDM also allows you to specify the way dependencies are added by default. As such, you can also specify upper-bounds (`^`) using PDM if require that approach." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:274 +msgid "Finally there are some nuanced differences in how both tools create lock files which we will not go into detail about here." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:277 +msgid "Challenges with PDM" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:279 +msgid "PDM is a full-featured packaging tool. However it is not without challenges:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:281 +msgid "Its documentation can be confusing, especially if you are new to packaging. For example, PDM doesn't provide an end to end beginning workflow in its documentation." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:283 +msgid "PDM also only has one maintainer currently. We consider individual maintainer teams to be a potential risk. If the maintainer finds they no longer have time to work on the project, it leaves users with a gap in support. Hatch and Flit also have single maintainer teams." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:288 +msgid "[You can view an example of a package that uses PDM here](https://github.com/pyOpenSci/examplePy/tree/main/example4_pdm). The README file for this directly provides you with an overview of what the PDM command line interface looks like when you use it." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:293 +msgid "[Flit is a no-frills, streamlined packaging tool](https://flit.pypa.io/en/stable/) that supports modern Python packaging standards. Flit is a great choice if you are building a basic package to use in a local workflow that doesn't require any advanced features. And if your package structure is already created. More on that below." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:297 +msgid "Flit Features" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:304 +msgid "Feature, Flit, Notes" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:304 +#: ../../package-structure-code/python-package-build-tools.md:348 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Publish to PyPI and test PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:304 +msgid "Flit supports publishing to both test PyPI and PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:304 +msgid "Helps you add metadata to your **pyproject.toml** file" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:304 +msgid "Flit does support adding metadata to your **pyproject.toml** file following modern packaging standards." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:304 +msgid "Flit supports current packaging standards for adding metadata to the **pyproject.toml** file." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:304 +msgid "Flit supports installing your package in editable mode.**" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:304 +msgid "Flit can be used to build your packages sdist and wheel distributions." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:311 +msgid "NOTE: _If you are using the most current version of pip, it supports both a symlink approach `flit install -s` and `python -m pip install -e .`_" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:313 +msgid "Learn more about flit" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:314 +msgid "[Why use flit?](https://flit.pypa.io/en/stable/rationale.html)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:317 +msgid "Why you might not want to use Flit" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:319 +msgid "Because Flit is no frills, it is best for basic, quick builds. If you are a beginner you may want to select Hatch or PDM which will offer you more support in common operations." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:323 +msgid "You may NOT want to use flit if:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:325 +msgid "You want to setup more advanced version tracking and management (using version control for version bumping)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:326 +msgid "You want a tool that handles dependency versions (use PDM or Poetry instead)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:327 +msgid "You have a project that is not pure Python (Use Hatch, PDM or setuptools)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:328 +msgid "You want environment management (use PDM, Hatch or Poetry)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:333 +msgid "[**Hatch**](https://hatch.pypa.io/latest/), similar to Poetry and PDM, provides a unified command line interface. To separate Hatch from Poetry and PDM, it also provides an environment manager for testing that will make it easier for you to run tests locally across different versions of Python. It also offers a nox / makefile like feature that allows you to create custom build workflows such as building your documentation locally. This means that you could potentially drop a tool like **Make** or **Nox** from your workflow and use Hatch instead." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:340 +msgid "Hatch features" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Feature, Hatch, Notes" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Hatch is used with the backend Hatchling by default, but allows you to use another backend by switching the declaration in pyproject.toml." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Currently you have to add dependencies manually with Hatch. However a feature to support dependencies management may be added in a future release." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Hatch supports Python virtual environments. If you wish to use other types of environments such as Conda, you will need to [install a plugin such as hatch-conda for conda support](https://github.com/OldGrumpyViking/hatch-conda)." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Hatch supports publishing to both test PyPI and PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Hatch offers `hatch_vcs` which is a plugin that uses setuptools_scm to support versioning using git tags. The workflow with `hatch_vcs` is the same as that with `setuptools_scm`." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Hatch supports you bumping the version of your package using standard semantic version terms patch; minor; major" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Hatch supports current packaging standards for adding metadata to the **pyproject.toml** file." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Hatch will install your package into any of its environments by default in editable mode. You can install your package in editable mode manually using `python -m pip install -e .` Hatch mentions [editable installs](https://hatch.pypa.io/latest/config/build/#dev-mode) but refers to pip in its documentation." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Hatch will build the sdist and wheel distributions" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "✨Matrix environment creation to support testing across Python versions✨" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "The matrix environment creation is a feature that is unique to Hatch in the packaging ecosystem. This feature is useful if you wish to test your package locally across Python versions (instead of using a tool such as tox)." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "✨[Nox / MAKEFILE like functionality](https://hatch.pypa.io/latest/environment/#selection)✨" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "This feature is also unique to Hatch. This functionality allows you to create workflows in the **pyproject.toml** configuration to do things like serve docs locally and clean your package build directory. This means you may have one less tool in your build workflow." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "✨A flexible build backend: **hatchling**✨" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "**The hatchling build backend offered by the maintainer of Hatch allows developers to easily build plugins to support custom build steps when packaging." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:362 +msgid "_There is some argument about this approach placing a burden on maintainers to create a custom build system. But others appreciate the flexibility. The Hatch build hook approach is also comparable with the features offered by PDM._" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:364 +msgid "Why you might not want to use Hatch" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:366 +msgid "There are a few features that hatch is missing that may be important for some. These include:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:369 +msgid "Hatch doesn't support adding dependencies. You will have to add them manually." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:370 +msgid "Hatch won't by default recognize Conda environments without a plugin." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:371 +msgid "Similar to PDM, Hatch's documentation can difficult to work through, particularly if you are just getting started with creating a package." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:372 +msgid "Hatch, similar to PDM and Flit currently only has one maintainer." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:376 +msgid "[Poetry is a full-featured build tool.](https://python-poetry.org/) It is also the second most popular front-end packaging tool (based upon the PyPA survey). Poetry is user-friendly and has clean and easy-to-read documentation." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:381 +msgid "While some have used Poetry for Python builds with C/C++ extensions, this support is currently undocumented. Thus, we don't recommend using Poetry for more complex builds." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:385 +msgid "Poetry features" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Feature, Poetry, Notes" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Poetry helps you add dependencies to your `pyproject.toml` metadata. _NOTE: currently Poetry adds dependencies using an approach that is slightly out of alignment with current Python peps - however there is a plan to fix this in an upcoming release._ Poetry also allows you to organize dependencies in groups such as documentation, packaging and tests." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Dependency specification" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Poetry allows you to be specific about version of dependencies that you add to your package's pyproject.toml file. However, it's default upper bound approach can be problematic for some packages (We suggest you override the default setting when adding dependencies). Read below for more." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Poetry allows you to either use its built in environment or you can select the environment type that you want to use for managing your package. [Read more about its built in environment management options](https://python-poetry.org/docs/basic-usage/#using-your-virtual-environment)." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Lock files" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Poetry creates a **poetry.lock** file that you can use if you need a lock file for your build." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Poetry supports publishing to both test PyPI and PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "The plugin [Poetry dynamic versioning](https://github.com/mtkennerly/poetry-dynamic-versioning) supports versioning using git tags with Poetry." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Poetry supports you bumping the version of your package using standard semantic version terms patch; minor; major" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "✖✅" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Poetry does not quite support current packaging standards for adding metadata to the **pyproject.toml** file but plans to fix this in an upcoming release." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Poetry supports installing your package in editable mode using `--editable`" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Poetry will build your sdist and wheel distributions using `poetry build`" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:407 +msgid "Challenges with Poetry" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:409 +msgid "Some challenges of Poetry include:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:411 +msgid "Poetry, by default, pins dependencies using an \"upper bound\" limit specified with the `^` symbol by default. However, this behavior can be over-written by specifying the dependency when you use `Poetry add` as follows: `poetry add \"requests>=2.1\"` See breakout below for more discussion on issues surrounding upper-bounds pinning." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:412 +msgid "_Minor Challenge:_ The way Poetry currently adds metadata to your pyproject.toml file does not follow current Python standards. However, this is going to be addressed with Poetry release version 2.0." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:414 +msgid "Poetry is an excellent tool. Use caution when using it to pin dependencies as Poetry's approach to pinning can be problematic for many builds. If you use Poetry, we strongly suggest that you override the default upper bound dependency option." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:420 +msgid "Challenges with Poetry dependency pinning" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:423 +msgid "By default, Poetry pins dependencies using `^` by default. This `^` symbol means that there is an \"upper bound\" to the dependency. Thus poetry won't bump a dependency version to a new major version. Thus, if your package uses a dependency that is at version 1.2.3, Poetry will never bump the dependency to 2.0 even if there is a new major version of the package. Poetry will instead bump up to 1.9.x." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:429 +msgid "Poetry does this because it adheres to strict semantic versioning which states that a major version bump (from 1.0 to 2.0 for example) means there are breaking changes in the tool. However, not all tools follow strict semantic versioning. [This approach has been found to be problematic by many of our core scientific packages.](https://iscinumpy.dev/post/bound-version-constraints/)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:434 +msgid "This approach also won't support others ways of versioning tools, for instance, some tools use [calver](https://calver.org/) which creates new versions based on the date." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:438 +msgid "Using Setuptools Back-end for Python Packaging with Build Front-end" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:440 +msgid "[Setuptools](https://setuptools.pypa.io/en/latest/) is the most mature Python packaging build tool with [development dating back to 2009 and earlier](https://setuptools.pypa.io/en/latest/history.html#). Setuptools also has the largest number of community users (according to the PyPA survey). Setuptools does not offer a user front-end like Flit, Poetry and Hatch offer. As such you will need to use other tools such as **build** to create your package distributions and **twine** to publish to PyPI." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:448 +msgid "While setuptools is the most commonly used tool, we encourage package maintainers to consider using a more modern tool for packaging such as Poetry, Hatch or PDM." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:451 +msgid "We discuss setuptools here because it's commonly found in the ecosystem and contributors may benefit from understanding it." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:454 +msgid "Setuptools Features" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:456 +msgid "Some of features of setuptools include:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:458 +msgid "Fully customizable build workflow" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:459 +msgid "Many scientific Python packages use it." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:460 +msgid "It offers version control based package versioning using **setuptools_scm**" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:461 +msgid "It supports modern packaging using **pyproject.toml** for metadata" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:462 +msgid "Supports backwards compatibly for older packaging approaches." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:464 +msgid "Challenges using setuptools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:468 +msgid "Setuptools has a few challenges:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:470 +msgid "Setuptools does not support interactive features such as auto / tab completion by default if you are working in an IDE like VSCODE and using an editable install for development. [See notes here about pylance support](https://github.com/microsoft/pylance-release/blob/main/TROUBLESHOOTING.md#editable-install-modules-not-found). In comparison, tools such as flit, hatch, PDM support interactive features such as tab / auto completion when using an IDE like VSCODE or pycharm (as long as your version of pip is current!)." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:471 +msgid "Because **setuptools** has to maintain backwards compatibility across a range of packages, it is not as flexible in its adoption of modern Python packaging standards." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:474 +msgid "The above-mentioned backwards compatibility makes for a more complex code-base." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:475 +msgid "Your experience as a user will be less streamlined and simple using setuptools compared to other tools discussed on this page." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:477 +msgid "There are also some problematic default settings that users should be aware of when using setuptools. For instance:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:480 +msgid "setuptools will build a project without a name or version if you are not using a **pyproject.toml** file to store metadata." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:482 +msgid "setuptools also will include all of the files in your package repository if you do not explicitly tell it to exclude files using a **MANIFEST.in** file" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:1 +msgid "Learn about Building a Python Package" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:8 +msgid "Once you have published both package distributions (the source distribution and the wheel) to PyPI, you can then publish to conda-forge. The conda-forge requires an 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 "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:11 +msgid "You need to build your Python package in order to publish it to PyPI (or a conda channel). 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. NOTE: you need to publish a sdist to PyPI in order for conda-forge to properly build your package automatically." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:14 +msgid "What is building a Python package?" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:16 +msgid "To [publish your Python package](publish-python-package-pypi-conda) and make it easy for anyone to install, you first need to build it." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:18 +msgid "But, what does it mean to build a Python package?" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:20 +msgid "[As shown in the figure above](#pypi-conda-channels), when you build your Python package, you convert the source files into something called a distribution package. A distribution package contains your source code and metadata about the package, in the format required by the Python Package Index, so that it can be installed by tools like pip." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:23 +msgid "The term package used to mean many different things in Python and other languages. On this page, we adapt the convention of the [Python Packaging Authority](https://www.pypa.io/en/latest/) and refer to the product of the build step as a **distribution package**." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:27 +msgid "This process of organizing and formatting your code, documentation, tests and metadata into a format that both pip and PyPI can use, is called a build step." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:31 +msgid "Project metadata and PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:33 +msgid "The metadata that both build tools and PyPI uses to describe and understand your package is generally stored in a [pyproject.toml file](pyproject-toml-python-package-metadata). This metadata is used for several purposes:" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:35 +msgid "It helps whatever tool you use to build your package (pip, [pypa's Build](https://pypi.org/project/build/) or an end-to-end tool such as poetry, PDM or Hatch) understand how to build your package. Information it provides to your build tool includes:" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:37 +msgid "The `[build-system]` table in your pyproject.toml file tells pip what [build backend tool](build_backends) you wish to use for creating your sdist and wheel distributions." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:45 +msgid "And the dependencies section of your project table tells the build tool and PyPI what dependencies your project requires." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:54 +msgid "When the build tool creates your package distribution file (the file that you publish on PyPI), it also creates a METADATA file which PyPI can read and use to help users find your package. For example:" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:56 +msgid "The `classifiers = ` section of your `[project]` table in the pyproject.toml file provides information that users on PyPI can use to filter for packages that contain specific licenses or that support specific versions of python." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:73 +msgid "What happened to setup.py and setup.cfg for metadata?" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:76 +msgid "Project metadata used to be stored in either a setup.py file or a setup.cfg file. The current recommended practice for storing package metadata is to use a pyproject.toml file. [Learn more about the pyproject.toml file here.](pyproject-toml-python-package-metadata)" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:79 +msgid "An example - xclim" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:81 +msgid "When you publish to PyPI, you will notice that each package has metadata listed. Let's have a look at [xclim](https://pypi.org/project/xclim/), one of our [pyOpenSci packages](https://www.pyopensci.org/python-packages.html). Notice that on the PyPI landing page you see some metadata about the package including python, maintainer information and more. PyPI is able to populate this metadata because it was defined using correct syntax and classifiers by Xclim's maintainers, [pyproject.toml file](https://github.com/Ouranosinc/xclim/blob/master/pyproject.toml). This metadata when the xclim package is built, is translated into a distribution file that allows PyPI to read the metadata and print it out on their website." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:94 +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 "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:96 +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. NOTE: you need to publish a sdist to PyPI in order for conda-forge to properly build your package automatically." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:101 +msgid "This screenshot shows the metadata on PyPI for the xclim package. On it you can see the name of the license, the author and maintainer names keywords associated with the package and the base python version it requires which is 3.8." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:103 +msgid "PyPI screenshot showing metadata for the xclim package." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:110 +msgid "Here you see the maintainer metadata as it is displayed on PyPI. For xclim there are three maintainers listed with their profile pictures and github user names to the right." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:112 +msgid "Maintainer names and GitHub usernames for the xclim package as they are displayed on PyPI. This information is recorded in your pyproject.toml and then processed by your build tool and stored in your packages sdist and wheel distributions." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:115 +msgid "How to create the distribution format that PyPI and Pip expects?" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:117 +msgid "You could in theory create your own scripts to organize your code the way PyPI wants it to be. However, just like there are packages that handle known structures such as Pandas for data frames and Numpy for arrays, there are packages and tools that help you create package build distribution files." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:121 +msgid "There are a suite of packaging tools that can either help you with the entire packaging process or just one step of the process. For instance setuptools is a commonly used build back end that can be used to create your sdist and wheel. Whereas tools like Hatch, PDM, Poetry and flit help with other parts of the packaging process." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:127 +msgid "While this can cause some confusion and complexity in the packaging ecosystem - for the most part, each tool provides the same distribution output (with minor differences that most users may not care about). Learn more about those tools on this page." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:133 +msgid "Below, you will learn about the two distribution files that PyPI expects you to publish: sdist and wheel. You will learn about their structure and what files belong in each." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:136 +msgid "There are two core distribution files that you need to create to publish your Python package to PyPI source distribution (often called an sdist) and wheel. The sdist contains the raw source code for your package. The wheel (.whl) contains the built / compiled files that can be directly installed onto anyones' computer." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:142 +msgid "Learn more about both distributions below." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:145 +msgid "If your package is a pure python package with no additional build / compilation steps then the sdist and wheel distributions will have similar content. However if your package has extensions in other languages or is more complex in its build, the two distributions will be very different." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:150 +msgid "Also note that we are not discussing conda build workflows in this section. [You can learn more about conda builds here.](https://conda.io/projects/conda-build/en/latest/user-guide/tutorials/index.html)" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:155 +msgid "What is a source distribution (sdist)" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:157 +msgid "**Source files** are the unbuilt files needed to build your package. These are the \"raw / as-is\" files that you store on GitHub or whatever platform you use to manage your code." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:161 +msgid "Source Distributions (**S** + **Dist**) are referred to as sdist. As the name implies, a SDIST contains the source code; it has not been built or compiled in any way. Thus, when a user installs your source distribution using pip, pip needs to run a build step first. For this reason, you could define a source distribution as a compressed archive that contains everything required to build a wheel (except for project dependencies) without network access." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:165 +msgid "Sdist is normally stored as a `.tar.gz` archive (often called a \"tarball\"). Thus, when a user installs your source distribution using pip, pip needs to run a build step first." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:167 +msgid "Below is an example sdist for the stravalib Python package:" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:219 +msgid "GitHub archive vs sdist" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:221 +msgid "When you make a release on GitHub, it creates a `git archive` that contains all of the files in your GitHub repository. While these files are similar to an sdist, these two archives are not the same. The sdist contains a few other items including a metadata directory and if you use `setuptools_scm` or `hatch_vcs` the sdist may also contain a file that stores the version." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:229 +msgid "What is a Python wheel (whl):" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:231 +msgid "A wheel file is a ZIP-format archive whose filename follows a specific format (below) and has the extension `.whl`. The `.whl` archive contains a specific set of files, including metadata that are generated from your project's pyproject.toml file. The pyproject.toml and other files that may be included in source distributions are not included in wheels because it is a built distribution." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:238 +msgid "The wheel (.whl) is your built binary distribution. **Binary files** are the built / compiled source files. These files are ready to be installed. A wheel (**.whl**) is a **zip** file containing all of the files needed to directly install your package. All of the files in a wheel are binaries - this means that code is already compiled / built. Wheels are thus faster to install - particularly if you have a package that requires build steps." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:240 +msgid "The wheel does not contain any of your package's configuration files such as **setup.cfg** or **pyproject.toml**. This distribution is already built so it's ready to install." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:244 +msgid "Because it is built, the wheel file will be faster to install for pure Python projects and can lead to consistent installs across machines." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:252 +msgid "Wheels are also useful in the case that a package needs a **setup.py** file to support a more complex build. In this case, because the files in the wheel bundle are pre built, the user installing doesn't have to worry about malicious code injections when it is installed." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:259 +msgid "The filename of a wheel contains important metadata about your package." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:261 +msgid "Example: **stravalib-1.1.0.post2-py3-none.whl**" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:263 +msgid "name: stravalib" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:264 +msgid "version: 1.1.0" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:265 +msgid "build-number: 2 (post2) [(read more about post here)](https://peps.python.org/pep-0440/#post-release-separators)" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:266 +msgid "py3: supports Python 3.x" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:267 +msgid "none: is not operating system specific (runs on windows, mac, linux)" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:268 +msgid "any: runs on any computer processor / architecture" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:270 +msgid "What a wheel file looks like when unpacked (unzipped):" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:304 +msgid "[Read more about the wheel format here](https://pythonwheels.com/)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:1 +msgid "Python Package Structure for Scientific Python Projects" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:3 +msgid "There are two different layouts that you will commonly see within the Python packaging ecosystem: src and flat layouts. Both layouts have advantages for different groups of maintainers." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:8 +msgid "We strongly suggest, but do not require, that you use the **src/** layout (discussed below) for creating your Python package. This layout is also recommended in the [PyPA packaging guide tutorial](https://packaging.python.org/en/latest/tutorials/packaging-projects/)." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:12 +msgid "pyOpenSci will never require a specific package structure for peer review" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:15 +msgid "We understand that it would take significant effort for existing maintainers to move to a new layout." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:18 +msgid "The overview on this page presents recommendations that we think are best for someone getting started with Python packaging or someone who's package has a simple build and might be open to moving to a more fail-proof approach." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:22 +msgid "Other resources you can check out:" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:23 +msgid "[PyPA's overview of src vs flat layouts](https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:26 +msgid "You can use tools like Hatch to quickly create a modern Python package structure. Check out our quickstart tutorial:" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:29 +msgid "Want to learn how to create the structure to build your package? Click here." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:37 +msgid "What is the Python package source layout?" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:39 +msgid "An example of the **src/package** layout structure is below." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:61 +msgid "Note the location of the following directories in the example above:" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:63 +msgid "**docs/:** Discussed in our docs chapter, this directory contains your user-facing documentation website. In a **src/** layout docs/ are normally included at the same directory level as the **src/** folder." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:64 +msgid "**tests/** This directory contains the tests for your project code. In a **src/** layout, tests are normally included at the same directory level as the **src/** folder." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:65 +msgid "**src/package/**: this is the directory that contains the code for your Python project. \"Package\" is normally your project's name." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:67 +msgid "Also in the above example, notice that all of the core documentation files that pyOpenSci requires live in the root of your project directory. These files include:" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:71 +msgid "CHANGELOG.md" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:72 +msgid "CODE_OF_CONDUCT.md" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:73 +msgid "CONTRIBUTING.md" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:74 +msgid "LICENSE.txt" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:75 +msgid "README.md" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:79 +msgid "Click here to read about our packaging documentation requirements." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:86 +msgid "Example scientific packages that use **src/package** layout" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:88 +msgid "[Sourmash](https://github.com/sourmash-bio/sourmash)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:89 +msgid "[bokeh](https://github.com/bokeh/bokeh)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:90 +msgid "[openscm](https://github.com/openscm/openscm-runner)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:91 +msgid "[awkward](https://github.com/scikit-hep/awkward)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:92 +msgid "[poliastro](https://github.com/poliastro/poliastro/)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:96 +msgid "The src/ layout and testing" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:98 +msgid "The benefit of using the **src/package** layout is that it ensures tests are run against the installed version of your package rather than the files in your package working directory. If you run your tests on your files rather than the installed version of your package, you may be missing issues that users encounter when your package is installed." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:104 +msgid "If `tests/` are outside the **src/package** directory, they aren't included in the package's [wheel](python-wheel). This makes your package size slightly smaller, which places a smaller storage burden on PyPI, and makes them faster to fetch." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:106 +msgid "[Read more about reasons to use the **src/package** layout](https://hynek.me/articles/testing-packaging/)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:108 +msgid "How Python discovers and prioritizes importing modules" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:110 +msgid "By default, Python adds a module in your current working directory to the front of the Python module search path." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:112 +msgid "This means that if you run your tests in your package's working directory, using a flat layout, `/package/module.py`, Python will discover `package/module.py` file before it discovers the installed package." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:114 +msgid "However, if your package lives in a src/ directory structure **src/package**, then it won't be added to the Python path by default. This means that when you import your package, Python will be forced to search the active environment (which has your package installed)." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:116 +msgid "Note: Python versions 3.11 and above have a path setting that can be adjusted to ensure the priority is to use installed packages first (e.g., `PYTHONSAFEPATH`)." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:119 +msgid "Don't include tests in your package wheel" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:121 +msgid "Writing [tests](tests-intro) for your package is important; however, we do not recommend including tests as part of your [package wheel](python-wheel) by default. However, not including tests in your package distribution will make it harder for people other than yourself to test whether your package runs properly on their system. If you have a small test suite (Python files + data), and think your users may want to run tests locally on their systems, you can include tests by moving the `tests/` directory into the **src/package** directory (see example below)." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:130 +msgid "Including the **tests/** directory in your **src/package** directory ensures that tests will be included in your package's [wheel](python-wheel)." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:132 +msgid "Be sure to read the [pytest documentation for more about including tests in your package distribution](https://docs.pytest.org/en/7.2.x/explanation/goodpractices.html#choosing-a-test-layout-import-rules)." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:134 +msgid "Challenges with including tests and data in a package wheel" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:137 +msgid "Tests, especially when accompanied by test data, can create a few small challenges, including:" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:139 +msgid "Take up space in your distribution, which will build up over time as storage space on PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:140 +msgid "Large file sizes can also slow down package installation." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:142 +msgid "However, in some cases, particularly in the scientific Python ecosystem, you may need to include tests." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:145 +msgid "**Don't include test suite datasets in your package**" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:147 +msgid "If you include your tests in your package distribution, we strongly discourage you from including data in your test suite directory. Rather, host your test data in a repository such as Figshare or Zenodo. Use a tool such as [Pooch](https://www.fatiando.org/pooch/latest/) to access the data when you (or a user) runs tests." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:153 +msgid "For more information about Python package tests, see the [tests section of our guide](tests-intro)." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:155 +msgid "The **src/package** layout is semantically more clear. Code is always found in the **src/package** directory, `tests/` and `docs/`are in the root directory." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:159 +msgid "If your package tests require data, do NOT include that data within your package structure. Including data in your package structure increases the size of your distribution files. This places a maintenance toll on repositories like PyPI and Anaconda.org that have to deal with thousands of package uploads." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:166 +msgid "Click here for a quickstart tutorial on creating your Python package." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:176 +msgid "What is the flat Python package layout?" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:178 +msgid "Many scientific packages use the **flat-layout** given:" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:180 +msgid "This layout is used by many core scientific Python packages such as NumPy, SciPy, and Matplotlib." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:181 +msgid "Many Python tools depend upon tools in other languages and/or complex builds with compilation steps. Many maintainers prefer features of the flat layout for more complex builds." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:185 +msgid "While we suggest that you use the **src/package** layout discussed above, it's important to also understand the flat layout, especially if you plan to contribute to a package that uses this layout." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:189 +msgid "Why most scientific Python packages do not use source" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:192 +msgid "In most cases, moving to the **src/package** layout for larger scientific packages that already use a flat layout would consume significant time." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:195 +msgid "However, the advantages of using the **src/package** layout for a beginner are significant. As such, we recommend that you use the **src/package** layout if you are creating a new package." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:198 +msgid "Numerous packages in the ecosystem [have had to move to a **src/package** layout](https://github.com/scikit-build/cmake-python-distributions/pull/145)." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:202 +msgid "What does the flat layout structure look like?" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:204 +msgid "The flat layout's primary characteristics are:" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:206 +msgid "The source code for your package lives in a directory with your package's name in the root of your directory" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:208 +msgid "Often the `tests/` directory also lives within that same `package` directory." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:210 +msgid "Below you can see the recommended structure of a scientific Python package using the flat layout." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:232 +msgid "Benefits of using the flat layout in your Python package" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:234 +msgid "There are some benefits to the scientific community in using the flat layout." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:236 +msgid "This structure has historically been used across the ecosystem and packages using it are unlikely to change." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:238 +msgid "You can import the package directly from the root directory. For some this is engrained in their respective workflows. However, for a beginner the danger of doing this is that you are not developing and testing against the installed version of your package. Rather, you are working directly with the flat files." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:244 +msgid "Core scientific Python packages that use the flat layout" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:247 +msgid "[numpy](https://github.com/numpy/numpy)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:248 +msgid "[scipy](https://github.com/scipy/scipy)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:249 +msgid "[pandas](https://github.com/pandas-dev/pandas)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:250 +msgid "[xarray](https://github.com/pydata/xarray)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:251 +msgid "[Jupyter-core](https://github.com/jupyter/jupyter_core)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:252 +msgid "[Jupyter notebook](https://github.com/jupyter/notebook)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:253 +msgid "[scikit-learn](https://github.com/scikit-learn/scikit-learn)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:255 +msgid "It would be a significant maintenance cost and burden to move all of these packages to a different layout. The potential benefits of the source layout for these tools are not worth the maintenance investment." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:1 +msgid "Creating New Versions of Your Python Package" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:6 +msgid "Key Takeways" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:8 +msgid "Follow [semantic versioning guidelines (SemVer) rules](https://semver.org/) when bumping (increasing) your Python's package version; for example a major version bump (version 1.0 --> 2.0) equates to breaking changes in your package's code for a user." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:9 +msgid "You may want to consider using a plugin like hatch_vsc for managing versions of your package - if you want to have a GitHub only release workflow." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:10 +msgid "Otherwise most major package build tools such as Hatch, Flit and PDM have a version feature that will help you update your package's version" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:11 +msgid "Avoid updating your packages version number manually by hand in your code!" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:14 +msgid "pyOpenSci recommends that you follow the [Python PEP 440](https://peps.python.org/pep-0440) which recommends using [semantic versioning guidelines](https://www.python.org/dev/peps/pep-0440/#semantic-versioning) when assigning release values to new versions of your Python package." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:18 +msgid "[Semantic versioning](https://semver.org/) is an approach to updating package versions that considers the type and extent of a change that you are making to the package code. Being consistent with how and when you update your package versions is important as:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:23 +msgid "It helps your users (which might include other developers that depend on your package) understand the extent of changes to a package." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:24 +msgid "It helps your development team make decisions about when to bump a package version based on standard rules." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:26 +msgid "Consistent version increases following semver rules mean that values of your package version explain the extent of the changes made in the code base from version to version. Thus your package version numbers become \"expressive\" in the same way that naming code variables well can [make code expressive](https://medium.com/@daniel.oliver.king/writing-expressive-code-b69ef7a5a2fa)." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:28 +msgid "A note about versioning" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:29 +msgid "In some cases even small version changes can turn a package update into a breaking change for some users. What is also important is that you document how you version your code and if you can, also document your deprecation policy for code." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:37 +msgid "SemVer rules" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:39 +msgid "Following SemVer, your bump your package version to a:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:41 +msgid "patch (1.1.1 --> 1.1.**2**)" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:42 +msgid "minor (1.1.1 --> 1.**2**.1)" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:43 +msgid "major (1.1.1 --> **2**.1.1)" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:45 +msgid "version number change based on the following rules:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:47 +msgid "Given a version number MAJOR.MINOR.PATCH, increment the:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:49 +msgid "**MAJOR version** when you make incompatible API changes" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:50 +msgid "**MINOR version** when you add functionality in a backwards compatible manner" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:51 +msgid "**PATCH version** when you make backwards compatible bug fixes Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:56 +msgid "Some people prefer to use [calver](https://calver.org/index.html) for versioning. It may be a simpler-to-use system given it relies upon date values associated with released versions. However, calver does not provide a user with a sense of when a new version might break an existing build. As such we still suggest semver." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:59 +msgid "pyOpenSci will never require semver in a peer review as long as a package has a reasonable approach to versioning!" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:63 +msgid "Avoid manually updating Python package version numbers if you can" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:65 +msgid "Often times you may want to have your package version value in multiple locations. One example of this is that it might be both an attribute in your package **version** and also called in your documentation." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:70 +msgid "We recommend that you avoid manual updates of your package version number to avoid human-error. It is better practice to keep your version number in one location." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:74 +msgid "If you can't implement a single location version, then consider using a tool like hatch, PDM or bump2version that will update the version values for you - throughout your package." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:78 +msgid "Below we discuss some tools that you can use to manage updating Python package versions." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:83 +msgid "Tools to manage versions for your Python package" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:85 +msgid "There are a handful of tools that are widely used in the scientific ecosystem that you can use to manage your package versions. Some of these tools are built into or work with your chosen [packaging build tools that discussed in this chapter.](python-package-build-tools)" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:91 +msgid "Below, we provide an overview of these tools." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:97 +msgid "There are three general groups of tools that you can use to manage package versions:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:100 +msgid "**semantic release tools:** These tools will automagically determine what type of version bump to use using the text in your commit messages. Below we discuss [Python Semantic Release](https://python-semantic-release.readthedocs.io/en/latest/) as a Python tool that implements a semantic versioning approach." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:102 +msgid "**Manual incremental bump tools:** Tools like [Hatch](https://hatch.pypa.io/latest/version/) offer version bumping within your package. Normally this is implemented at the command link for instance `hatch version major` would bump your project from 0.x to 1.0." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:103 +msgid "**Version Control System tools:** Finally there are tools that rely on your version control system to track versions. These tools often are plugins to your package build tool (ex: setuptools build or hatchling). We discuss this option below assuming that you are using **.git tags** and **GitHub** to manage your package repository." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:105 +msgid "Semantic release, vs version control based vs manual version bumping" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:107 +msgid "Generally semantic release and version control system tools can be setup to run automatically on GitHub using GitHub Actions. This means that you can create a workflow where a GitHub release and associated new version tag is used to trigger an automated build that:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:113 +msgid "Builds your package and updates the version following the new tag" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:114 +msgid "Tests the build and publishes to test PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:115 +msgid "Publishes the package to PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:118 +msgid "Bumping a package version refers to the step of increasing the package version after a set number of changes have been made to it. For example, you might bump from version 0.8 to 0.9 of a package or from 0.9 to 1.0." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:122 +msgid "Using semantic versioning, there are three main \"levels\" of versions that you might consider:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:125 +msgid "Major, minor and patch. These are described in more detail below." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:128 +msgid "Tools for bumping Python package versions" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:130 +msgid "In this section we discuss the following tools for managing your Python package's version:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:133 +msgid "hatch &" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:134 +msgid "hatch_vcs plugin for hatchling" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:135 +msgid "setuptools-scm" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:136 +msgid "python-semantic-version" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:138 +msgid "Tool 1: Hatch and other build tools that offer incremental versioning" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:140 +msgid "Many of the modern build tool front end tools offer version support that follow semantic versioning rules. These tools are different from Python Semantic Version in that they do not require specific commit messages to implement version. Rather, they allow you to update the version at the command line using commands such as:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:146 +msgid "`tool-name version update major`" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:147 +msgid "`tool-name version update minor`" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:149 +msgid "[Hatch](https://hatch.pypa.io/latest/version/), for instance offers `hatch version minor` which will modify the version of your package incrementally. With **Hatch** the version value will be found in your `pyproject.toml` file. " +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:152 +msgid "Hatch (or other tools like PDM) Pros" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:154 +msgid "Easy to use version updates locally using a single tool!" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:156 +msgid "Hatch (or other tools like PDM) Cons" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:158 +msgid "There will be some setup involved to ensure package version is updated throughout your package" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:160 +msgid "Tool 2: Hatch_vcs & hatchling build back-end" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:162 +msgid "[hatch_vcs](https://github.com/ofek/hatch-vcs) is a versioning tool that allows you to manage package versions using **git tags**. Hatch_vcs creates a **\\_version.py** file in your package ecosystem that keeps track of the package's current version." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:167 +msgid "Hatch keeps track of your package's version in a `_version.py` file. Storing the version in a single file managed by Hatch provides your package with a \"single source of truth\" value for the version number. This in turn eliminates potential error associated with manually updating your package's version." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:173 +msgid "When you (or your CI system) build your package, hatch checks the current tag number for your package. If it has increased, it will update the **\\_version.py** file with the new value." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:176 +msgid "Thus, when you create a new tag or a new release with a tag and build your package, Hatch will access the new tag value and use it to update your package version." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:179 +msgid "To use **hatch_vcs** you will need to use the **hatchling** build back end." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:182 +msgid "Hatchling can also be used with any of the modern build tools including **Flit** and **PDM** if you prefer those for your day to day workflow." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:187 +msgid "Hatch example setup in your pyproject.toml" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:196 +msgid "**Hatch_vcs** supports a fully automated package release and build, and push to PyPI workflow on GitHub." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:206 +msgid "If you use **setuptools_scm**, then you might find **hatch_vcs** and **hatchling** to be the modern equivalent to your current setuptools / build workflow." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:209 +msgid "hatch_vcs Pros" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:211 +msgid "Hatch supports modern Python packaging standards" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:212 +#: ../../package-structure-code/python-package-versions.md:238 +msgid "It creates a single-source file that contains your package version." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:213 +#: ../../package-structure-code/python-package-versions.md:239 +msgid "You never manually update the package version" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:214 +#: ../../package-structure-code/python-package-versions.md:240 +msgid "You can automate writing the version anywhere in your package including your documentation!" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:215 +#: ../../package-structure-code/python-package-versions.md:241 +msgid "It supports a purely GitHub based release workflow. This simplifies maintenance workflows." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:216 +#: ../../package-structure-code/python-package-versions.md:242 +msgid "Version number is updated in your package via a hidden `_version.py` file. There is no manual configuration updates required." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:217 +#: ../../package-structure-code/python-package-versions.md:243 +msgid "While we like detailed commit messages (See Python Semantic Version below), we know that sometimes when maintaining a package specific guidelines around commit messages can be hard to apply and manage." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:219 +msgid "hatch_vcs Cons" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:221 +msgid "In a CI workflow you will end up manually entering or creating the version number via a tag on GitHub. But you could locally develop a build to \"bump\" tag versions" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:224 +msgid "Tool 3: setuptools-scm versioning using git tags" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:226 +msgid "[`Setuptools_scm`](https://github.com/pypa/setuptools_scm/) is an extension that you can use with setuptools to manage package versions. **Setuptools_scm** operates the same way that **hatch_vcs** (discussed above) does. It stores a version in a **\\_version.py** file and relies on (**git**) tags to determine the package's current version." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:232 +msgid "If you are using **setuptools** as your primary build tool, then `*setuptools-scm` is a good choice as:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:236 +msgid "setuptools_scm Pros" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:244 +msgid "**setuptools** is still the most commonly used Python packaging build tool" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:246 +msgid "setuptools_scm Cons" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:248 +msgid "In a CI workflow you will end up manually entering or creating the version number via a tag on GitHub." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:249 +msgid "Not well documented" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:250 +msgid "Because setuptools will always have to support backwards compatibility it will always be slower in adopting modern Python packaging conventions." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:252 +msgid "As such you might consider using a more modern tool such as **hatch_vcs** and **hatchling** to build your package and manage package versions." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:264 +msgid "Tool 4: [Python semantic release](https://python-semantic-release.readthedocs.io/en/latest/)" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:266 +msgid "Python semantic release uses a commit message workflow that updates the version of your package based on keywords found in your commit messages. As the name implies, Python Semantic Release follows semver release rules." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:271 +msgid "With Python Semantic Release, versions are triggered using specific language found in a git commit message." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:274 +msgid "For example, the words `fix(attribute_warning):` trigger Python Semantic Release to implement a **patch** version bump. For instance if your package was at version 1.1.0 and you made the commit below with the words fix(text-here), Python Semantic Release would bump your package to version 1.1.1." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:284 +msgid "Similarly a feature (`feat()`) triggers a minor version bump. For example from version 1.1 to version 1.2" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:292 +msgid "You can find a thoughtful discussion of python semantic version [in this Python package guide](https://py-pkgs.org/07-releasing-versioning#automatic-version-bumping). Note that the guide hasn't been updated since 2020 and will potentially be updated in the future! But for now, some of the commands are dated but the content is still excellent." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:295 +msgid "Python Semantic Release Pros" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:297 +msgid "Follows semver versioning closely" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:298 +msgid "Enforces maintainers using descriptive commit messages which can simplify troubleshooting and ensure a cleaner and more self-describing git history." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:300 +msgid "Python Semantic Release Cons" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:302 +msgid "Requires very specific commit language to work. In practice some maintainers and contributors may not be able to maintain that level of specificity in commit messages (NOTE: there are bots that will check git commit messages in a repo)" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:303 +msgid "Release happens at the command line. This makes is harder to implement a GitHub based release workflow as the wrong commit message could trigger a release." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:304 +msgid "The version number is manually updated in a configuration file such as `pyproject.toml` vs. in a package **\\_version.py** file." +msgstr "" diff --git a/locales/templates/LC_MESSAGES/tests.pot b/locales/templates/LC_MESSAGES/tests.pot new file mode 100644 index 00000000..4456a86b --- /dev/null +++ b/locales/templates/LC_MESSAGES/tests.pot @@ -0,0 +1,779 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2025, pyOpenSci +# This file is distributed under the same license as the pyOpenSci Python Package Guide package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: pyOpenSci Python Package Guide \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-04-30 18:44-0600\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../../tests/code-cov.md:1 +msgid "Code coverage for your Python package test suite" +msgstr "" + +#: ../../tests/code-cov.md:3 +msgid "Code coverage measures how much of your package's code runs during testing. Achieving high coverage can help ensure the reliability of your codebase, but it’s not a guarantee of quality. Below, we outline key considerations for using code coverage effectively." +msgstr "" + +#: ../../tests/code-cov.md:8 +msgid "Why aim for high code coverage?" +msgstr "" + +#: ../../tests/code-cov.md:10 +msgid "A good practice is to ensure that every line of your code runs at least once during your test suite. This helps you:" +msgstr "" + +#: ../../tests/code-cov.md:13 +msgid "Identify untested parts of your codebase." +msgstr "" + +#: ../../tests/code-cov.md:14 +msgid "Catch bugs that might otherwise go unnoticed." +msgstr "" + +#: ../../tests/code-cov.md:15 +msgid "Build confidence in your software's stability." +msgstr "" + +#: ../../tests/code-cov.md:17 +msgid "Limitations of code coverage" +msgstr "" + +#: ../../tests/code-cov.md:19 +msgid "While high code coverage is valuable, it has its limits:" +msgstr "" + +#: ../../tests/code-cov.md:21 +msgid "**Difficult-to-test code:** Some parts of your code might be challenging to test, either due to complexity or limited resources." +msgstr "" + +#: ../../tests/code-cov.md:23 +msgid "**Missed edge cases:** Running all lines of code doesn’t guarantee that edge cases are handled correctly." +msgstr "" + +#: ../../tests/code-cov.md:26 +msgid "Ultimately, you should focus on how your package will be used and ensure your tests cover those scenarios adequately." +msgstr "" + +#: ../../tests/code-cov.md:29 +msgid "Tools for analyzing Python package code coverage" +msgstr "" + +#: ../../tests/code-cov.md:31 +msgid "Some common services for analyzing code coverage are [codecov.io](https://codecov.io/) and [coveralls.io](https://coveralls.io/). These projects are free for open source tools and will provide dashboards that tell you how much of your codebase is covered during your tests. We recommend setting up an account (on either CodeCov or Coveralls) and using it to keep track of your code coverage." +msgstr "" + +#: ../../tests/code-cov.md:33 +msgid "Screenshot of the code cov service - showing test coverage for the stravalib package. This image shows a list of package modules and the associated number of lines and % lines covered by tests. At the top of the image, you can see what branch is being evaluated and the path to the repository." +msgstr "" + +#: ../../tests/code-cov.md:38 +msgid "The CodeCov platform is a useful tool if you wish to track code coverage visually. Using it, you can not only get the same summary information that you can get with the **pytest-cov** extension. You can also see what lines are covered by your tests and which are not. Code coverage is useful for evaluating unit tests and/or how much of your package code is \"covered\". It, however, will not evaluate things like integration tests and end-to-end workflows." +msgstr "" + +#: ../../tests/code-cov.md:43 +msgid "Typing & MyPy coverage" +msgstr "" + +#: ../../tests/code-cov.md:44 +msgid "You can also create and upload typing reports to CodeCov." +msgstr "" + +#: ../../tests/code-cov.md:47 +msgid "Exporting Local Coverage Reports" +msgstr "" + +#: ../../tests/code-cov.md:49 +msgid "In addition to using services like CodeCov or Coveralls, you can generate local coverage reports directly using the **coverage.py** tool. This can be especially useful if you want to create reports in Markdown or HTML format for offline use or documentation." +msgstr "" + +#: ../../tests/code-cov.md:51 +msgid "To generate a coverage report in **Markdown** format, run:" +msgstr "" + +#: ../../tests/code-cov.md:56 +msgid "This command will produce a Markdown-formatted coverage summary that you can easily include in project documentation or share with your team." +msgstr "" + +#: ../../tests/code-cov.md:58 +msgid "To generate an HTML report that provides a detailed, interactive view of which lines are covered, use:" +msgstr "" + +#: ../../tests/code-cov.md:64 +msgid "The generated HTML report will be saved in a directory named htmlcov by default. Open the index.html file in your browser to explore your coverage results." +msgstr "" + +#: ../../tests/code-cov.md:66 +msgid "These local reports are an excellent way to quickly review coverage without setting up an external service." +msgstr "" + +#: ../../tests/index.md:73 +msgid "Intro" +msgstr "" + +#: ../../tests/index.md:73 +msgid "Write tests" +msgstr "" + +#: ../../tests/index.md:73 +msgid "Test types" +msgstr "" + +#: ../../tests/index.md:73 +msgid "Run tests locally" +msgstr "" + +#: ../../tests/index.md:73 +msgid "Run tests online (using CI)" +msgstr "" + +#: ../../tests/index.md:73 +msgid "Code coverage" +msgstr "" + +#: ../../tests/index.md:73 +msgid "Create & Run Tests" +msgstr "" + +#: ../../tests/index.md:2 +msgid "Tests and data for your Python package" +msgstr "" + +#: ../../tests/index.md:4 +msgid "Tests are an important part of your Python package because they provide a set of checks that ensure that your package is functioning how you expect it to." +msgstr "" + +#: ../../tests/index.md:8 +msgid "In this section, you will learn more about the importance of writing tests for your Python package and how you can set up infrastructure to run your tests both locally and on GitHub." +msgstr "" + +#: ../../tests/index.md:20 +msgid "✨ Why write tests ✨" +msgstr "" + +#: ../../tests/index.md:25 +msgid "Learn more about the art of writing tests for your Python package. Learn about why you should write tests and how they can help you and potential contributors to your project." +msgstr "" + +#: ../../tests/index.md:32 +msgid "✨ Types of tests ✨" +msgstr "" + +#: ../../tests/index.md:37 +msgid "There are three general types of tests that you can write for your Python package: unit tests, integration tests and end-to-end (or functional) tests. Learn about all three." +msgstr "" + +#: ../../tests/index.md:43 +msgid "✨ Run tests locally ✨" +msgstr "" + +#: ../../tests/index.md:48 +msgid "If you expect your users to use your package across different versions of Python, then using an automation tool such as nox to run your tests is useful. Learn about the various tools that you can use to run your tests across python versions here." +msgstr "" + +#: ../../tests/index.md:54 +msgid "✨ Run tests online (using CI) ✨" +msgstr "" + +#: ../../tests/index.md:59 +msgid "Continuous integration platforms such as GitHub Actions can be useful for running your tests across both different Python versions and different operating systems. Learn about setting up tests to run in Continuous Integration here." +msgstr "" + +#: ../../tests/index.md:70 +msgid "Graphic showing the elements of the packaging process." +msgstr "" + +#: ../../tests/run-tests.md:6 +msgid "Run Python package tests" +msgstr "" + +#: ../../tests/run-tests.md:8 +msgid "Running your tests is important to ensure that your package is working as expected. It's good practice to consider that tests will run on your computer and your users' computers that may be running a different Python version and operating systems. Think about the following when running your tests:" +msgstr "" + +#: ../../tests/run-tests.md:11 +msgid "Run your test suite in a matrix of environments that represent the Python versions and operating systems your users are likely to have." +msgstr "" + +#: ../../tests/run-tests.md:12 +msgid "Running your tests in an isolated environment provides confidence in the tests and their reproducibility. This ensures that tests do not pass randomly due to your computer's specific setup. For instance, you might have unexpectedly installed dependencies on your local system that are not declared in your package's dependency list. This oversight could lead to issues when others try to install or run your package on their computers." +msgstr "" + +#: ../../tests/run-tests.md:14 +msgid "On this page, you will learn about the tools that you can use to both run tests in isolated environments and across Python versions." +msgstr "" + +#: ../../tests/run-tests.md:19 +msgid "Tools to run your tests" +msgstr "" + +#: ../../tests/run-tests.md:21 +msgid "There are three categories of tools that will make is easier to setup and run your tests in various environments:" +msgstr "" + +#: ../../tests/run-tests.md:24 +msgid "A **test framework**, is a package that provides a particular syntax and set of tools for _both writing and running your tests_. Some test frameworks also have plugins that add additional features such as evaluating how much of your code the tests cover. Below you will learn about the **pytest** framework which is one of the most commonly used Python testing frameworks in the scientific ecosystem. Testing frameworks are essential but they only serve to run your tests. These frameworks don't provide a way to easily run tests across Python versions without the aid of additional automation tools." +msgstr "" + +#: ../../tests/run-tests.md:25 +msgid "**Automation tools** allow you to automate running workflows such as tests in specific ways using user-defined commands. For instance it's useful to be able to run tests across different Python versions with a single command. Tools such as [**nox**](https://nox.thea.codes/en/stable/index.html) and [**tox**](https://tox.wiki/en/latest/index.html) also allow you to run tests across Python versions. However, it will be difficult to test your build on different operating systems using only nox and tox - this is where continuous integration (CI) comes into play." +msgstr "" + +#: ../../tests/run-tests.md:26 +msgid "**Continuous Integration (CI):** is the last tool that you'll need to run your tests. CI will not only allow you to replicate any automated builds you create using nox or tox to run your package in different Python environments. It will also allow you to run your tests on different operating systems (Windows, Mac and Linux). [We discuss using CI to run tests here](tests-ci)." +msgstr "" + +#: ../../tests/run-tests.md:28 +msgid "Table: Testing & Automation Tool" +msgstr "" + +#: ../../tests/run-tests.md:35 +msgid "Features" +msgstr "" + +#: ../../tests/run-tests.md:36 +msgid "Testing Framework (pytest)" +msgstr "" + +#: ../../tests/run-tests.md:37 +msgid "Test Runner (Tox)" +msgstr "" + +#: ../../tests/run-tests.md:38 +msgid "Automation Tools (Nox)" +msgstr "" + +#: ../../tests/run-tests.md:39 +msgid "Continuous Integration (GitHub Actions)" +msgstr "" + +#: ../../tests/run-tests.md:40 +msgid "Run Tests Locally" +msgstr "" + +#: ../../tests/run-tests.md:41 +#: ../../tests/run-tests.md:42 +#: ../../tests/run-tests.md:43 +#: ../../tests/run-tests.md:49 +#: ../../tests/run-tests.md:52 +#: ../../tests/run-tests.md:53 +#: ../../tests/run-tests.md:54 +#: ../../tests/run-tests.md:57 +#: ../../tests/run-tests.md:58 +#: ../../tests/run-tests.md:59 +#: ../../tests/run-tests.md:64 +#: ../../tests/run-tests.md:68 +#: ../../tests/run-tests.md:69 +msgid "" +msgstr "" + +#: ../../tests/run-tests.md:44 +#: ../../tests/run-tests.md:46 +#: ../../tests/run-tests.md:47 +#: ../../tests/run-tests.md:48 +#: ../../tests/run-tests.md:51 +#: ../../tests/run-tests.md:56 +#: ../../tests/run-tests.md:61 +#: ../../tests/run-tests.md:62 +#: ../../tests/run-tests.md:63 +#: ../../tests/run-tests.md:66 +#: ../../tests/run-tests.md:67 +msgid "" +msgstr "" + +#: ../../tests/run-tests.md:45 +msgid "Run Tests Online" +msgstr "" + +#: ../../tests/run-tests.md:50 +msgid "Run Tests Across Python Versions" +msgstr "" + +#: ../../tests/run-tests.md:55 +msgid "Run Tests In Isolated Environments" +msgstr "" + +#: ../../tests/run-tests.md:60 +msgid "Run Tests Across Operating Systems (Windows, MacOS, Linux)" +msgstr "" + +#: ../../tests/run-tests.md:65 +msgid "Use for other automation tasks (e.g. building docs)" +msgstr "" + +#: ../../tests/run-tests.md:73 +msgid "What testing framework / package should I use to run tests?" +msgstr "" + +#: ../../tests/run-tests.md:75 +msgid "We recommend using `Pytest` to build and run your package tests. Pytest is the most common testing tool used in the Python ecosystem." +msgstr "" + +#: ../../tests/run-tests.md:77 +msgid "[The Pytest package](https://docs.pytest.org/en/latest/) also has a number of extensions that can be used to add functionality such as:" +msgstr "" + +#: ../../tests/run-tests.md:80 +msgid "[pytest-cov](https://pytest-cov.readthedocs.io/en/latest/) allows you to analyze the code coverage of your package during your tests, and generates a report that you can [upload to codecov](https://codecov.io/)." +msgstr "" + +#: ../../tests/run-tests.md:82 +#: ../../tests/run-tests.md:174 +#: ../../tests/test-types.md:14 +#: ../../tests/tests-ci.md:7 +msgid "Todo" +msgstr "" + +#: ../../tests/run-tests.md:83 +msgid "Learn more about code coverage here. (add link)" +msgstr "" + +#: ../../tests/run-tests.md:87 +msgid "Your editor or IDE may add additional convenience for running tests, setting breakpoints, and toggling the `–no-cov` flag. Check your editor's documentation for more information." +msgstr "" + +#: ../../tests/run-tests.md:90 +msgid "Run tests using pytest" +msgstr "" + +#: ../../tests/run-tests.md:92 +msgid "If you are using **pytest**, you can run your tests locally by calling:" +msgstr "" + +#: ../../tests/run-tests.md:95 +msgid "`pytest`" +msgstr "" + +#: ../../tests/run-tests.md:97 +msgid "Or if you want to run a specific test file - let's call this file \"`test_module.py`\" - you can run:" +msgstr "" + +#: ../../tests/run-tests.md:99 +msgid "`pytest test_module.py`" +msgstr "" + +#: ../../tests/run-tests.md:101 +msgid "Learn more from the [get started docs](https://docs.pytest.org/en/7.1.x/getting-started.html)." +msgstr "" + +#: ../../tests/run-tests.md:103 +msgid "Running pytest on your computer is going to run your tests in whatever Python environment you currently have activated. This means that tests will be run on a single version of Python and only on the operating system that you are running locally." +msgstr "" + +#: ../../tests/run-tests.md:108 +msgid "An automation tool can simplify the process of running tests in various Python environments." +msgstr "" + +#: ../../tests/run-tests.md:111 +msgid "Tests across operating systems" +msgstr "" + +#: ../../tests/run-tests.md:112 +msgid "If you want to run your tests across different operating systems you can [continuous integration. Learn more here](tests-ci)." +msgstr "" + +#: ../../tests/run-tests.md:115 +msgid "Tools to automate running your tests" +msgstr "" + +#: ../../tests/run-tests.md:117 +msgid "To run tests on various Python versions or in various specific environments with a single command, you can use an automation tool such as `nox` or `tox`. Both `nox` and `tox` can create an isolated virtual environments. This allows you to easily run your tests in multiple environments and across Python versions." +msgstr "" + +#: ../../tests/run-tests.md:120 +msgid "We will focus on [Nox](https://nox.thea.codes/) in this guide. `nox` is a Python-based automation tool that builds upon the features of both `make` and `tox`. `nox` is designed to simplify and streamline testing and development workflows. Everything that you do with `nox` can be implemented using a Python-based interface." +msgstr "" + +#: ../../tests/run-tests.md:122 +msgid "Other automation tools you'll see in the wild" +msgstr "" + +#: ../../tests/run-tests.md:125 +msgid "**[Tox](https://tox.wiki/en/latest/index.html#useful-links)** is an automation tool that supports common steps such as building documentation, running tests across various versions of Python, and more." +msgstr "" + +#: ../../tests/run-tests.md:127 +msgid "**[Hatch](https://github.com/ofek/hatch)** is a modern end-to-end packaging tool that works with the popular build backend called hatchling. `hatch` offers a `tox`-like setup where you can run tests locally using different Python versions. If you are using `hatch` to support your packaging workflow, you may want to also use its testing capabilities rather than using `nox`." +msgstr "" + +#: ../../tests/run-tests.md:129 +msgid "[**make:**](https://www.gnu.org/software/make/manual/make.html) Some developers use Make, which is a build automation tool, for running tests due to its versatility; it's not tied to a specific language and can be used to run various build processes. However, Make's unique syntax and approach can make it more challenging to learn, particularly if you're not already familiar with it. Make also won't manage environments for you like **nox** will do." +msgstr "" + +#: ../../tests/run-tests.md:136 +msgid "Run tests across Python versions with nox" +msgstr "" + +#: ../../tests/run-tests.md:138 +msgid "**Nox** is a great automation tool to learn because it:" +msgstr "" + +#: ../../tests/run-tests.md:140 +msgid "Is Python-based making it accessible if you already know Python and" +msgstr "" + +#: ../../tests/run-tests.md:141 +msgid "Will create isolated environments to run workflows." +msgstr "" + +#: ../../tests/run-tests.md:143 +msgid "`nox` simplifies creating and managing testing environments. With `nox`, you can set up virtual environments, and run tests across Python versions using the environment manager of your choice with a single command." +msgstr "" + +#: ../../tests/run-tests.md:148 +msgid "Nox Installations" +msgstr "" + +#: ../../tests/run-tests.md:150 +msgid "When you install and use nox to run tests across different Python versions, nox will create and manage individual `venv` environments for each Python version that you specify in the nox function." +msgstr "" + +#: ../../tests/run-tests.md:152 +msgid "Nox will manage each environment on its own." +msgstr "" + +#: ../../tests/run-tests.md:154 +msgid "Nox can also be used for other development tasks such as building documentation, creating your package distribution, and testing installations across both PyPI related environments (e.g. venv, virtualenv) and `conda` (e.g. `conda-forge`)." +msgstr "" + +#: ../../tests/run-tests.md:158 +msgid "To get started with nox, you create a `noxfile.py` file at the root of your project directory. You then define commands using Python functions. Some examples of that are below." +msgstr "" + +#: ../../tests/run-tests.md:162 +msgid "Test Environments" +msgstr "" + +#: ../../tests/run-tests.md:164 +msgid "By default, `nox` uses the Python built in `venv` environment manager. A virtual environment (`venv`) is a self-contained Python environment that allows you to isolate and manage dependencies for different Python projects. It helps ensure that project-specific libraries and packages do not interfere with each other, promoting a clean and organized development environment." +msgstr "" + +#: ../../tests/run-tests.md:166 +msgid "An example of using nox to run tests in `venv` environments for Python versions 3.9, 3.10, 3.11 and 3.12 is below." +msgstr "" + +#: ../../tests/run-tests.md:169 +msgid "Note that for the code below to work, you need to have all 4 versions of Python installed on your computer for `nox` to find." +msgstr "" + +#: ../../tests/run-tests.md:172 +msgid "Nox with venv environments" +msgstr "" + +#: ../../tests/run-tests.md:175 +msgid "TODO: add some tests above and show what the output would look like in the examples below..." +msgstr "" + +#: ../../tests/run-tests.md:178 +msgid "Below is an example of setting up nox to run tests using `venv` which is the built in environment manager that comes with base Python." +msgstr "" + +#: ../../tests/run-tests.md:180 +msgid "Note that the example below assumes that you have [setup your `pyproject.toml` to declare test dependencies in a way that pip can understand](../package-structure-code/declare-dependencies.md). An example of that setup is below." +msgstr "" + +#: ../../tests/run-tests.md:201 +msgid "If you have the above setup, then you can use `session.install(\".[tests]\")` to install your test dependencies. Notice that below one single nox session allows you to run your tests on 4 different Python environments (Python 3.9, 3.10, 3.11, and 3.12)." +msgstr "" + +#: ../../tests/run-tests.md:222 +msgid "Above you create a nox session in the form of a function with a `@nox.session` decorator. Notice that within the decorator you declare the versions of python that you wish to run." +msgstr "" + +#: ../../tests/run-tests.md:226 +msgid "To run the above you'd execute the following command, specifying which session with `--session` (sometimes shortened to `-s`). Your function above is called test, therefore the session name is test." +msgstr "" + +#: ../../tests/run-tests.md:234 +msgid "Nox with conda / mamba" +msgstr "" + +#: ../../tests/run-tests.md:236 +msgid "Below is an example for setting up nox to use mamba (or conda) for your environment manager. Note that unlike venv, conda can automatically install the various versions of Python that you need. You won't need to install all four Python versions if you use conda/mamba, like you do with `venv`." +msgstr "" + +#: ../../tests/run-tests.md:242 +msgid "For `conda` to work with `nox`, you will need to ensure that either `conda` or `mamba` is installed on your computer." +msgstr "" + +#: ../../tests/run-tests.md:264 +msgid "To run the above session you'd use:" +msgstr "" + +#: ../../tests/test-types.md:1 +msgid "Test Types for Python packages" +msgstr "" + +#: ../../tests/test-types.md:3 +msgid "Three types of tests: Unit, Integration & Functional Tests" +msgstr "" + +#: ../../tests/test-types.md:5 +msgid "There are different types of tests that you want to consider when creating your test suite:" +msgstr "" + +#: ../../tests/test-types.md:8 +msgid "Unit tests" +msgstr "" + +#: ../../tests/test-types.md:9 +msgid "Integration" +msgstr "" + +#: ../../tests/test-types.md:10 +msgid "End-to-end (also known as Functional) tests" +msgstr "" + +#: ../../tests/test-types.md:12 +msgid "Each type of test has a different purpose. Here, you will learn about all three types of tests." +msgstr "" + +#: ../../tests/test-types.md:15 +msgid "I think this page would be stronger if we did have some examples from our package here: https://github.com/pyOpenSci/pyosPackage" +msgstr "" + +#: ../../tests/test-types.md:20 +msgid "Unit Tests" +msgstr "" + +#: ../../tests/test-types.md:22 +msgid "A unit test involves testing individual components or units of code in isolation to ensure that they work correctly. The goal of unit testing is to verify that each part of the software, typically at the function or method level, performs its intended task correctly." +msgstr "" + +#: ../../tests/test-types.md:24 +msgid "Unit tests can be compared to examining each piece of your puzzle to ensure parts of it are not broken. If all of the pieces of your puzzle don’t fit together, you will never complete it. Similarly, when working with code, tests ensure that each function, attribute, class, method works properly when isolated." +msgstr "" + +#: ../../tests/test-types.md:26 +msgid "**Unit test example:** Pretend that you have a function that converts a temperature value from Celsius to Fahrenheit. A test for that function might ensure that when provided with a value in Celsius, the function returns the correct value in degrees Fahrenheit. That function is a unit test. It checks a single unit (function) in your code." +msgstr "" + +#: ../../tests/test-types.md:44 +msgid "Example unit test for the above function. You'd run this test using the `pytest` command in your **tests/** directory." +msgstr "" + +#: ../../tests/test-types.md:65 +#: ../../tests/test-types.md:115 +msgid "image of puzzle pieces that all fit together nicely. The puzzle pieces are colorful - purple, green and teal." +msgstr "" + +#: ../../tests/test-types.md:69 +msgid "Your unit tests should ensure each part of your code works as expected on its own." +msgstr "" + +#: ../../tests/test-types.md:72 +msgid "Integration tests" +msgstr "" + +#: ../../tests/test-types.md:74 +msgid "Integration tests involve testing how parts of your package work together or integrate. Integration tests can be compared to connecting a bunch of puzzle pieces together to form a whole picture. Integration tests focus on how different pieces of your code fit and work together." +msgstr "" + +#: ../../tests/test-types.md:76 +msgid "For example, if you had a series of steps that collected temperature data in a spreadsheet, converted it from degrees celsius to Fahrenheit and then provided an average temperature for a particular time period. An integration test would ensure that all parts of that workflow behaved as expected." +msgstr "" + +#: ../../tests/test-types.md:107 +msgid "image of two puzzle pieces with some missing parts. The puzzle pieces are purple teal yellow and blue. The shapes of each piece don’t fit together." +msgstr "" + +#: ../../tests/test-types.md:112 +msgid "If puzzle pieces have missing ends, they can’t work together with other elements in the puzzle. The same is true with individual functions, methods and classes in your software. The code needs to work both individually and together to perform certain sets of tasks." +msgstr "" + +#: ../../tests/test-types.md:120 +msgid "Your integration tests should ensure that parts of your code that are expected to work together, do so as expected." +msgstr "" + +#: ../../tests/test-types.md:124 +msgid "End-to-end (functional) tests" +msgstr "" + +#: ../../tests/test-types.md:126 +msgid "End-to-end tests (also referred to as functional tests) in Python are like comprehensive checklists for your software. They simulate real user end-to-end workflows to make sure the code base supports real life applications and use-cases from start to finish. These tests help catch issues that might not show up in smaller tests and ensure your entire application or program behaves correctly. Think of them as a way to give your software a final check before it's put into action, making sure it's ready to deliver a smooth experience to its users." +msgstr "" + +#: ../../tests/test-types.md:128 +msgid "Image of a completed puzzle showing a daisy" +msgstr "" + +#: ../../tests/test-types.md:133 +msgid "End-to-end or functional tests represent an entire workflow that you expect your package to support." +msgstr "" + +#: ../../tests/test-types.md:137 +msgid "End-to-end test also test how a program runs from start to finish. A tutorial that you add to your documentation that runs in CI in an isolated environment is another example of an end-to-end test." +msgstr "" + +#: ../../tests/test-types.md:140 +msgid "For scientific packages, creating short tutorials that highlight core workflows that your package supports, that are run when your documentation is built could also serve as end-to-end tests." +msgstr "" + +#: ../../tests/test-types.md:143 +msgid "Comparing unit, integration and end-to-end tests" +msgstr "" + +#: ../../tests/test-types.md:145 +msgid "Unit tests, integration tests, and end-to-end tests have complementary advantages and disadvantages. The fine-grained nature of unit tests make them well-suited for isolating where errors are occurring. However, unit tests are not useful for verifying that different sections of code work together." +msgstr "" + +#: ../../tests/test-types.md:147 +msgid "Integration and end-to-end tests verify that the different portions of the program work together, but are less well-suited for isolating where errors are occurring. For example, when you refactor your code, it is possible that that your end-to-end tests will break. But if the refactor didn't introduce new behavior to your existing code, then you can rely on your unit tests to continue to pass, testing the original functionality of your code." +msgstr "" + +#: ../../tests/test-types.md:152 +msgid "It is important to note that you don't need to spend energy worrying about the specifics surrounding the different types of tests. When you begin to work on your test suite, consider what your package does and how you may need to test parts of your package. Bring familiar with the different types of tests can provides a framework to help you think about writing tests and how different types of tests can complement each other." +msgstr "" + +#: ../../tests/tests-ci.md:1 +msgid "Run tests with Continuous Integration" +msgstr "" + +#: ../../tests/tests-ci.md:3 +msgid "Running your [test suite locally](run-tests) is useful as you develop code and also test new features or changes to the code base. However, you also will want to setup Continuous Integration (CI) to run your tests online. CI allows you to run all of your tests in the cloud. While you may only be able to run tests locally on a specific operating system, using CI you can specify tests to run both on various versions of Python and across different operating systems." +msgstr "" + +#: ../../tests/tests-ci.md:5 +msgid "CI can also be triggered for pull requests and pushes to your repository. This means that every pull request that you, your maintainer team or a contributor submit, can be tested. In the end CI testing ensures your code continues to run as expected even as changes are made to the code base." +msgstr "" + +#: ../../tests/tests-ci.md:9 +msgid "Learn more about Continuous Integration and how it can be used, here. (add link)" +msgstr "" + +#: ../../tests/tests-ci.md:13 +msgid "CI & pull requests" +msgstr "" + +#: ../../tests/tests-ci.md:15 +msgid "CI is invaluable if you have outside people contributing to your software. You can setup CI to run on all pull requests submitted to your repository. CI can make your repository more friendly to new potential contributors. It allows users to contribute code, documentation fixes and more without having to create development environments, run tests and build documentation locally." +msgstr "" + +#: ../../tests/tests-ci.md:22 +msgid "Example GitHub Actions that runs tests" +msgstr "" + +#: ../../tests/tests-ci.md:24 +msgid "Below is an example GitHub Actions that runs tests using nox across both Windows, Mac and Linux and on Python versions 3.9-3.11." +msgstr "" + +#: ../../tests/tests-ci.md:28 +msgid "To work properly, this file should be located in a root directory of your GitHub repository:" +msgstr "" + +#: ../../tests/write-tests.md:1 +msgid "Write tests for your Python package" +msgstr "" + +#: ../../tests/write-tests.md:3 +msgid "Writing code that tests your package code, also known as test suites, is important for you as a maintainer, your users, and package contributors. Test suites consist of sets of functions, methods, and classes that are written with the intention of making sure a specific part of your code works as you expected it to." +msgstr "" + +#: ../../tests/write-tests.md:7 +msgid "Why write tests for your package?" +msgstr "" + +#: ../../tests/write-tests.md:9 +msgid "Tests act as a safety net for code changes. They help you spot and rectify bugs before they affect users. Tests also instill confidence that code alterations from contributors won't breaking existing functionality." +msgstr "" + +#: ../../tests/write-tests.md:13 +msgid "Writing tests for your Python package is important because:" +msgstr "" + +#: ../../tests/write-tests.md:15 +msgid "**Catch Mistakes:** Tests are a safety net. When you make changes or add new features to your package, tests can quickly tell you if you accidentally broke something that was working fine before." +msgstr "" + +#: ../../tests/write-tests.md:16 +msgid "**Save Time:** Imagine you have a magic button that can automatically check if your package is still working properly. Tests are like that magic button! They can run all those checks for you saving you time." +msgstr "" + +#: ../../tests/write-tests.md:17 +msgid "**Easier Collaboration:** If you're working with others, or have outside contributors, tests help everyone stay on the same page. Your tests explain how your package is supposed to work, making it easier for others to understand and contribute to your project." +msgstr "" + +#: ../../tests/write-tests.md:18 +msgid "**Fearless Refactoring:** Refactoring means making improvements to your code structure without changing its behavior. Tests empower you to make these changes as if you break something, test failures will let you know." +msgstr "" + +#: ../../tests/write-tests.md:19 +msgid "**Documentation:** Tests serve as technical examples of how to use your package. This can be helpful for a new technical contributor that wants to contribute code to your package. They can look at your tests to understand how parts of your code functionality fits together." +msgstr "" + +#: ../../tests/write-tests.md:20 +msgid "**Long-Term ease of maintenance:** As your package evolves, tests ensure that your code continues to behave as expected, even as you make changes over time. Thus you are helping your future self when writing tests." +msgstr "" + +#: ../../tests/write-tests.md:21 +msgid "**Easier pull request reviews:** By running your tests in a CI framework such as GitHub Actions, each time you or a contributor makes a change to your code-base, you can catch issues and things that may have changed in your code base. This ensures that your software behaves the way you expect it to." +msgstr "" + +#: ../../tests/write-tests.md:23 +msgid "Tests for user edge cases" +msgstr "" + +#: ../../tests/write-tests.md:25 +msgid "Edge cases refer to unexpected or \"outlier\" ways that some users may use your package. Tests enable you to address various edge cases that could impair your package's functionality. For example, what occurs if a function expects a pandas `dataframe` but a user supplies a numpy `array`? Does your code gracefully handle this situation, providing clear feedback, or does it leave users frustrated by an unexplained failure?" +msgstr "" + +#: ../../tests/write-tests.md:33 +msgid "For a good introduction to testing, see [this Software Carpentry lesson](https://swcarpentry.github.io/python-novice-inflammation/10-defensive.html)" +msgstr "" + +#: ../../tests/write-tests.md:41 +msgid "Imagine you're working on a puzzle where each puzzle piece represents a function, method, class or attribute in your Python package that you want other people to be able to use. Would you want to give someone a puzzle that has missing pieces or pieces that don't fit together? Providing people with the right puzzle pieces that work together can be compared to writing tests for your Python package." +msgstr "" + +#: ../../tests/write-tests.md:44 +msgid "Test examples" +msgstr "" + +#: ../../tests/write-tests.md:47 +msgid "Let’s say you have a Python function that adds two numbers a and b together." +msgstr "" + +#: ../../tests/write-tests.md:54 +msgid "A test to ensure that function runs as you might expect when provided with different numbers might look like this:" +msgstr "" + +#: ../../tests/write-tests.md:72 +msgid "🧩🐍" +msgstr "" + +#: ../../tests/write-tests.md:74 +msgid "How do I know what type of tests to write?" +msgstr "" + +#: ../../tests/write-tests.md:77 +msgid "This section has been adapted from [a presentation by Nick Murphy](https://zenodo.org/record/8185113)." +msgstr "" + +#: ../../tests/write-tests.md:80 +msgid "At this point, you may be wondering - what should you be testing in your package? Below are a few examples:" +msgstr "" + +#: ../../tests/write-tests.md:82 +msgid "**Test some typical cases:** Test that the package functions as you expect it to when users use it. For instance, if your package is supposed to add two numbers, test that the outcome value of adding those two numbers is correct." +msgstr "" + +#: ../../tests/write-tests.md:84 +msgid "**Test special cases:** Sometimes there are special or outlier cases. For instance, if a function performs a specific calculation that may become problematic closer to the value = 0, test it with the input of both 0 and" +msgstr "" + +#: ../../tests/write-tests.md:86 +msgid "**Test at and near the expected boundaries:** If a function requires a value that is greater than or equal to 1, make sure that the function still works with both the values 1 and less than one and 1.001 as well (something close to the constraint value).." +msgstr "" + +#: ../../tests/write-tests.md:88 +msgid "**Test that code fails correctly:** If a function requires a value greater than or equal to 1, then test at 0.999. Make sure that the function fails gracefully when given unexpected values and help and that the user can easily understand why if failed (provides a useful error message)." +msgstr "" diff --git a/locales/templates/LC_MESSAGES/tutorials.pot b/locales/templates/LC_MESSAGES/tutorials.pot new file mode 100644 index 00000000..9a26f079 --- /dev/null +++ b/locales/templates/LC_MESSAGES/tutorials.pot @@ -0,0 +1,3970 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2025, pyOpenSci +# This file is distributed under the same license as the pyOpenSci Python Package Guide package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: pyOpenSci Python Package Guide \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-04-30 18:44-0600\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\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/noxfile.py b/noxfile.py index fe70c482..7c203c85 100644 --- a/noxfile.py +++ b/noxfile.py @@ -13,7 +13,7 @@ ## Sphinx related options # Sphinx output and source directories -BUILD_DIR = '_build' +BUILD_DIR = "_build" OUTPUT_DIR = pathlib.Path(BUILD_DIR, "html") SOURCE_DIR = pathlib.Path(".") @@ -29,7 +29,7 @@ BUILD_PARAMETERS = ["-b", "html"] # Sphinx parameters used to test the build of the guide -TEST_PARAMETERS = ['--keep-going', '-E', '-a'] +TEST_PARAMETERS = ["--keep-going", "-E", "-a"] # Sphinx parameters to generate translation templates TRANSLATION_TEMPLATE_PARAMETERS = ["-b", "gettext"] @@ -41,9 +41,7 @@ "build_assets", "tmp", ] -AUTOBUILD_INCLUDE = [ - pathlib.Path("_static", "pyos.css") -] +AUTOBUILD_INCLUDE = [pathlib.Path("_static", "pyos.css")] ## Localization options (translations) @@ -54,14 +52,21 @@ RELEASE_LANGUAGES = conf.release_languages # allowable values of `SPHINX_ENV` -SPHINX_ENVS = ('production', 'development') +SPHINX_ENVS = ("production", "development") + @nox.session def docs(session): """Build the packaging guide.""" session.install("-e", ".") sphinx_env = _sphinx_env(session) - session.run(SPHINX_BUILD, *BUILD_PARAMETERS, SOURCE_DIR, OUTPUT_DIR, *session.posargs) + session.run( + SPHINX_BUILD, + *BUILD_PARAMETERS, + SOURCE_DIR, + OUTPUT_DIR, + *session.posargs, + ) # When building the guide, also build the translations in RELEASE_LANGUAGES session.notify("build-release-languages", session.posargs) @@ -74,14 +79,30 @@ def docs_test(session): Note: this is the session used in CI/CD to release the guide. """ session.install("-e", ".") - session.run(SPHINX_BUILD, *BUILD_PARAMETERS, *TEST_PARAMETERS, SOURCE_DIR, OUTPUT_DIR, *session.posargs, - env={'SPHINX_ENV': 'production'}) + session.run( + SPHINX_BUILD, + *BUILD_PARAMETERS, + *TEST_PARAMETERS, + SOURCE_DIR, + OUTPUT_DIR, + *session.posargs, + env={"SPHINX_ENV": "production"}, + ) # When building the guide with additional parameters, also build the translations in RELEASE_LANGUAGES # with those same parameters. - session.notify("build-release-languages", [*TEST_PARAMETERS, *session.posargs]) - -def _autobuild_cmd(posargs: list[str], output_dir = OUTPUT_DIR) -> list[str]: - cmd = [SPHINX_AUTO_BUILD, *BUILD_PARAMETERS, str(SOURCE_DIR), str(output_dir), *posargs] + session.notify( + "build-release-languages", [*TEST_PARAMETERS, *session.posargs] + ) + + +def _autobuild_cmd(posargs: list[str], output_dir=OUTPUT_DIR) -> list[str]: + cmd = [ + SPHINX_AUTO_BUILD, + *BUILD_PARAMETERS, + str(SOURCE_DIR), + str(output_dir), + *posargs, + ] for folder in AUTOBUILD_IGNORE: cmd.extend(["--ignore", f"*/{folder}/*"]) return cmd @@ -107,7 +128,7 @@ def docs_live(session): # This part was commented in the previous version of the nox file, keeping the same here # for folder in AUTOBUILD_INCLUDE: # cmd.extend(["--watch", folder]) - session.run(*cmd, env={'SPHINX_ENV': "development"}) + session.run(*cmd, env={"SPHINX_ENV": "development"}) @nox.session(name="docs-live-lang") @@ -133,7 +154,9 @@ def docs_live_lang(session): lang = session.posargs[0] if lang in LANGUAGES: session.posargs.pop(0) - session.notify("docs-live", ('-D', f"language={lang}", *session.posargs)) + session.notify( + "docs-live", ("-D", f"language={lang}", *session.posargs) + ) else: session.error( f"[{lang}] locale is not available. Try using:\n\n " @@ -141,6 +164,7 @@ def docs_live_lang(session): f"where LANG is one of: {LANGUAGES}" ) + @nox.session(name="docs-live-langs") def docs_live_langs(session): """ @@ -149,37 +173,63 @@ def docs_live_langs(session): Requires concurrently to run (npm install -g concurrently) """ try: - subprocess.check_call(['concurrently'], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL) + subprocess.check_call( + ["concurrently"], + stdout=subprocess.DEVNULL, + stderr=subprocess.DEVNULL, + ) except subprocess.CalledProcessError: # handle errors in the called executable # (aka, was found) pass except OSError: - session.error('docs-live-langs requires concurrently (npm install -g concurrently)') + session.error( + "docs-live-langs requires concurrently (npm install -g concurrently)" + ) session.install("-e", ".") - cmds = ['"' + " ".join(["SPHINX_ENV=development"] + _autobuild_cmd(session.posargs) + ['--open-browser']) + '"'] + cmds = [ + '"' + + " ".join( + ["SPHINX_ENV=development"] + + _autobuild_cmd(session.posargs) + + ["--open-browser"] + ) + + '"' + ] for language in LANGUAGES: cmds.append( - '"' + " ".join( - [f"SPHINX_LANG={language}", "SPHINX_ENV=development"] + - _autobuild_cmd( + '"' + + " ".join( + [f"SPHINX_LANG={language}", "SPHINX_ENV=development"] + + _autobuild_cmd( session.posargs + ["-D", f"language={language}"], - output_dir=OUTPUT_DIR / language - ) + ["--port=0"] - ) + '"' + output_dir=OUTPUT_DIR / language, + ) + + ["--port=0"] + ) + + '"' ) - cmd = ['concurrently', '--kill-others', '-n', ','.join(["en"] + LANGUAGES), '-c', 'auto', *cmds] + cmd = [ + "concurrently", + "--kill-others", + "-n", + ",".join(["en"] + LANGUAGES), + "-c", + "auto", + *cmds, + ] session.run(*cmd) + @nox.session(name="docs-clean") def clean_dir(session): """Clean out the docs directory used in the live build.""" session.warn(f"Cleaning out {OUTPUT_DIR}") - dir_contents = OUTPUT_DIR.glob('*') + dir_contents = OUTPUT_DIR.glob("*") for content in dir_contents: - session.log(f'removing {content}') + session.log(f"removing {content}") if content.is_dir(): shutil.rmtree(content) else: @@ -198,10 +248,23 @@ def update_release_languages(session): session.install("-e", ".") session.install("sphinx-intl") session.log("Updating templates (.pot)") - session.run(SPHINX_BUILD, *TRANSLATION_TEMPLATE_PARAMETERS, SOURCE_DIR, TRANSLATION_TEMPLATE_DIR, *session.posargs) + session.run( + SPHINX_BUILD, + *TRANSLATION_TEMPLATE_PARAMETERS, + SOURCE_DIR, + TRANSLATION_TEMPLATE_DIR, + *session.posargs, + ) for lang in RELEASE_LANGUAGES: session.log(f"Updating .po files for [{lang}] translation") - session.run("sphinx-intl", "update", "-p", TRANSLATION_TEMPLATE_DIR, "-l", lang) + session.run( + "sphinx-intl", + "update", + "-p", + TRANSLATION_TEMPLATE_DIR, + "-l", + lang, + ) else: session.warn("No release languages defined in RELEASE_LANGUAGES") @@ -219,9 +282,22 @@ def update_language(session): session.install("-e", ".") session.install("sphinx-intl") session.log("Updating templates (.pot)") - session.run(SPHINX_BUILD, *TRANSLATION_TEMPLATE_PARAMETERS, SOURCE_DIR, TRANSLATION_TEMPLATE_DIR, *session.posargs) + session.run( + SPHINX_BUILD, + *TRANSLATION_TEMPLATE_PARAMETERS, + SOURCE_DIR, + TRANSLATION_TEMPLATE_DIR, + *session.posargs, + ) session.log(f"Updating .po files for [{lang}] translation") - session.run("sphinx-intl", "update", "-p", TRANSLATION_TEMPLATE_DIR, "-l", lang) + session.run( + "sphinx-intl", + "update", + "-p", + TRANSLATION_TEMPLATE_DIR, + "-l", + lang, + ) else: f"[{lang}] locale is not available. Try using:\n\n " "nox -s docs-live-lang -- LANG\n\n " @@ -233,7 +309,9 @@ def update_language(session): f" where LANG is one of: {LANGUAGES}" ) if not session.posargs: - session.error("Please provide the list of languages to build the translation for") + session.error( + "Please provide the list of languages to build the translation for" + ) sphinx_env = _sphinx_env(session) @@ -251,7 +329,15 @@ def build_language(session): if lang in LANGUAGES: session.install("-e", ".") session.log(f"Building [{lang}] guide") - session.run(SPHINX_BUILD, *BUILD_PARAMETERS, "-D", f"language={lang}", ".", OUTPUT_DIR / lang, *session.posargs) + session.run( + SPHINX_BUILD, + *BUILD_PARAMETERS, + "-D", + f"language={lang}", + ".", + OUTPUT_DIR / lang, + *session.posargs, + ) else: session.error(f"Language {lang} is not in LANGUAGES list.") else: @@ -274,15 +360,32 @@ def build_release_languages(session): session.install("-e", ".") for lang in RELEASE_LANGUAGES: session.log(f"Building [{lang}] guide") - session.run(SPHINX_BUILD, *BUILD_PARAMETERS, "-D", f"language={lang}", ".", OUTPUT_DIR / lang, *session.posargs) - if lang == 'en': + session.run( + SPHINX_BUILD, + *BUILD_PARAMETERS, + "-D", + f"language={lang}", + ".", + OUTPUT_DIR / lang, + *session.posargs, + ) + if lang == "en": out_dir = OUTPUT_DIR else: out_dir = OUTPUT_DIR / lang - session.run(SPHINX_BUILD, *BUILD_PARAMETERS, "-D", f"language={lang}", ".", out_dir, *session.posargs, - env={"SPHINX_LANG": lang, "SPHINX_ENV": sphinx_env}) + session.run( + SPHINX_BUILD, + *BUILD_PARAMETERS, + "-D", + f"language={lang}", + ".", + out_dir, + *session.posargs, + env={"SPHINX_LANG": lang, "SPHINX_ENV": sphinx_env}, + ) session.log(f"Translations built for {RELEASE_LANGUAGES}") + @nox.session(name="build-all-languages") def build_all_languages(session): """ @@ -294,21 +397,39 @@ def build_all_languages(session): session.install("-e", ".") for lang in LANGUAGES: session.log(f"Building [{lang}] guide") - session.run(SPHINX_BUILD, *BUILD_PARAMETERS, "-D", f"language={lang}", ".", OUTPUT_DIR / lang, *session.posargs) + session.run( + SPHINX_BUILD, + *BUILD_PARAMETERS, + "-D", + f"language={lang}", + ".", + OUTPUT_DIR / lang, + *session.posargs, + ) session.log(f"Translations built for {LANGUAGES}") sphinx_env = _sphinx_env(session) # if running from the docs or docs-test sessions, build only release languages - BUILD_LANGUAGES = RELEASE_LANGUAGES if sphinx_env == "production" else LANGUAGES + BUILD_LANGUAGES = ( + RELEASE_LANGUAGES if sphinx_env == "production" else LANGUAGES + ) # only build languages that have a locale folder - BUILD_LANGUAGES = [lang for lang in BUILD_LANGUAGES if (TRANSLATION_LOCALES_DIR / lang).exists()] + BUILD_LANGUAGES = [ + lang + for lang in BUILD_LANGUAGES + if (TRANSLATION_LOCALES_DIR / lang).exists() + ] session.log(f"Declared languages: {LANGUAGES}") session.log(f"Release languages: {RELEASE_LANGUAGES}") - session.log(f"Building languages{' for release' if sphinx_env == 'production' else ''}: {BUILD_LANGUAGES}") + session.log( + f"Building languages{' for release' if sphinx_env == 'production' else ''}: {BUILD_LANGUAGES}" + ) if not BUILD_LANGUAGES: session.warn("No translations to build") else: - session.notify("build-languages", [sphinx_env, BUILD_LANGUAGES, *session.posargs]) + session.notify( + "build-languages", [sphinx_env, BUILD_LANGUAGES, *session.posargs] + ) @nox.session(name="build-all-languages-test") @@ -330,4 +451,35 @@ def _sphinx_env(session) -> str: if session.posargs and session.posargs[0] in SPHINX_ENVS: return session.posargs.pop(0) else: - return os.environ.get('SPHINX_ENV', 'development') + return os.environ.get("SPHINX_ENV", "development") + + +@nox.session(name="create_pot_crowdin") +def create_pot_crowdin(session): + """ + Generate .pot file(s) from the source Markdown using Sphinx; copy all into + locales/templates/LC_MESSAGES/ for Crowdin syncing. + """ + session.install("-e", ".") + session.install("sphinx-intl") + + # Generate .pot files from .md sources + session.log("Extracting .pot templates with Sphinx") + session.run( + SPHINX_BUILD, + *TRANSLATION_TEMPLATE_PARAMETERS, + str(SOURCE_DIR), + str(TRANSLATION_TEMPLATE_DIR), + ) + + # Copy .pot files to LC_MESSAGES for Crowdin + template_target = pathlib.Path("locales/templates/LC_MESSAGES") + template_target.mkdir(parents=True, exist_ok=True) + pot_files = list(TRANSLATION_TEMPLATE_DIR.glob("*.pot")) + + if not pot_files: + session.error("No .pot files found in _build/gettext/") + else: + for pot_file in pot_files: + session.log(f"Copying {pot_file.name}") + shutil.copy(pot_file, template_target / pot_file.name)