diff --git a/conf.py b/conf.py index beedf3eed..ffc4e2deb 100644 --- a/conf.py +++ b/conf.py @@ -42,7 +42,7 @@ language = language_env # all languages that have .po files generated for them # (excluding english) -languages = ["es", "ja"] +languages = ["es", "ja", "pt"] # the languages that will be included in a production build # (also excluding english) release_languages = ["ja"] diff --git a/locales/pt/LC_MESSAGES/CONTRIBUTING.po b/locales/pt/LC_MESSAGES/CONTRIBUTING.po new file mode 100644 index 000000000..29863f4de --- /dev/null +++ b/locales/pt/LC_MESSAGES/CONTRIBUTING.po @@ -0,0 +1,723 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2026, pyOpenSci +# This file is distributed under the same license as the pyOpenSci Python +# Package Guide package. +# FIRST AUTHOR , 2026. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: pyOpenSci Python Package Guide \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-05-18 10:26-0700\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: pt\n" +"Language-Team: pt \n" +"Plural-Forms: nplurals=2; plural=(n != 1);\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.18.0\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://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-linkcheck`: this session checks that links in documentation work" +msgstr "" + +#: ../../CONTRIBUTING.md:195 +msgid "" +"If the tests fail, you will see logs in the terminal and in " +"`_build/linkcheck_output/output.txt`." +msgstr "" + +#: ../../CONTRIBUTING.md:197 +msgid "`docs-test`: this session runs the tests for the guide." +msgstr "" + +#: ../../CONTRIBUTING.md:201 +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:203 +msgid "" +"`docs-live`: this session builds the guide and opens it in your browser " +"with live reloading." +msgstr "" + +#: ../../CONTRIBUTING.md:207 +msgid "" +"open the local version of the guide in your browser at ``localhost`` " +"shown in the terminal." +msgstr "" + +#: ../../CONTRIBUTING.md:209 +msgid "Before you submit your pull request" +msgstr "" + +#: ../../CONTRIBUTING.md:211 +msgid "" +"Before submitting your pull request, make sure to run the tests and check" +" the formatting of your code." +msgstr "" + +#: ../../CONTRIBUTING.md:216 +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:220 +msgid "Submitting a pull request with your contribution" +msgstr "" + +#: ../../CONTRIBUTING.md:222 +msgid "How to make a pull request" +msgstr "" + +#: ../../CONTRIBUTING.md:224 +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:226 +msgid "Pull requests tab in GitHub" +msgstr "" + +#: ../../CONTRIBUTING.md:232 +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:235 +msgid "Click on the \"New pull request\" button." +msgstr "" + +#: ../../CONTRIBUTING.md:237 +msgid "New pull request button in GitHub" +msgstr "" + +#: ../../CONTRIBUTING.md:243 +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:246 +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:248 +msgid "What happens when you submit a pull request (CI/CD)" +msgstr "" + +#: ../../CONTRIBUTING.md:250 +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:252 +msgid "" +"**Code formatting and styles**: checks that your code is formatted " +"correctly, by `pre-commit.ci - pr check`." +msgstr "" + +#: ../../CONTRIBUTING.md:253 +msgid "" +"**docs build**: checks that the documentation builds correctly, using " +"`circleci`." +msgstr "" + +#: ../../CONTRIBUTING.md:255 +msgid "You will see the status of these checks in your pull request." +msgstr "" + +#: ../../CONTRIBUTING.md:257 +msgid "Pull request checks in GitHub" +msgstr "" + +#: ../../CONTRIBUTING.md:263 +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:265 +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:267 +msgid "Pull request checks failed in GitHub" +msgstr "" + +#: ../../CONTRIBUTING.md:273 +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:276 +msgid "" +"To get more information about the errors, you can click on the " +"\"Details\" link next to the failed check." +msgstr "" + +#: ../../CONTRIBUTING.md:278 +msgid "What to expect from the review process" +msgstr "" + +#: ../../CONTRIBUTING.md:280 +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:282 +msgid "" +"**Comments**: the reviewer may leave comments on your pull request to ask" +" questions or provide feedback." +msgstr "" + +#: ../../CONTRIBUTING.md:283 +msgid "" +"**Suggestions**: the reviewer may suggest changes to your code or " +"documentation." +msgstr "" + +#: ../../CONTRIBUTING.md:284 +msgid "" +"**Approvals**: once the reviewer is satisfied with your changes, they " +"will approve the pull request." +msgstr "" + +#: ../../CONTRIBUTING.md:286 +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:288 +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:290 +msgid "Additional help" +msgstr "" + +#: ../../CONTRIBUTING.md:292 +msgid "How to get help" +msgstr "" + +#: ../../CONTRIBUTING.md:294 +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:296 +msgid "Additional resources" +msgstr "" + +#: ../../CONTRIBUTING.md:298 +msgid "" +"*__TODO__: It should also include links to beginner documentation, like " +"the GitHub docs.*" +msgstr "" + +#: ../../CONTRIBUTING.md:300 +msgid "Annex" +msgstr "" + +#: ../../CONTRIBUTING.md:302 +msgid "Code examples" +msgstr "" + +#: ../../CONTRIBUTING.md:304 +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:308 +msgid "Referencing code in documentation" +msgstr "" + +#: ../../CONTRIBUTING.md:310 +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:313 +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:318 +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:322 +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:325 +msgid "Creating code for documentation" +msgstr "" + +#: ../../CONTRIBUTING.md:327 +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:331 +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:335 +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:339 +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:342 +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:350 +msgid "Example:" +msgstr "" + +#: ../../CONTRIBUTING.md:352 +msgid "Instead of writing example code in markdown like this" +msgstr "" + +#: ../../CONTRIBUTING.md:363 +msgid "The python can be extracted into a `.py` file" +msgstr "" + +#: ../../CONTRIBUTING.md:377 +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:380 +msgid "Instead of writing this" +msgstr "" + +#: ../../CONTRIBUTING.md:391 +msgid "an example could be extracted from an existing toml file" +msgstr "" diff --git a/locales/pt/LC_MESSAGES/TRANSLATING.po b/locales/pt/LC_MESSAGES/TRANSLATING.po new file mode 100644 index 000000000..796edfa23 --- /dev/null +++ b/locales/pt/LC_MESSAGES/TRANSLATING.po @@ -0,0 +1,729 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2026, pyOpenSci +# This file is distributed under the same license as the pyOpenSci Python +# Package Guide package. +# FIRST AUTHOR , 2026. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: pyOpenSci Python Package Guide \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-05-18 10:26-0700\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: pt\n" +"Language-Team: pt \n" +"Plural-Forms: nplurals=2; plural=(n != 1);\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.18.0\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 "Translation Status" +msgstr "" + +#: ../../TRANSLATING.md:16 +msgid "Overview of the Translation Process" +msgstr "" + +#: ../../TRANSLATING.md:18 +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:20 +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:22 +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:24 +msgid "Here is a quick overview of how the translation process works:" +msgstr "" + +#: ../../TRANSLATING.md:26 +msgid "" +"The guide is originally written in English and stored in a set of " +"MarkDown files." +msgstr "" + +#: ../../TRANSLATING.md:27 +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:28 +msgid "" +"Contributors (like you!) translate these files into the different " +"languages." +msgstr "" + +#: ../../TRANSLATING.md:29 +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:32 +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:35 +msgid "Setting up Your Local Environment" +msgstr "" + +#: ../../TRANSLATING.md:37 +msgid "Before you start, you will need to set up your local work environment." +msgstr "" + +#: ../../TRANSLATING.md:39 +msgid "" +"First, fork the guide repository into your personal GitHub account and " +"clone the forked repository to your local computer." +msgstr "" + +#: ../../TRANSLATING.md:41 +msgid "" +"To create a virtual environment and install the development dependencies " +"for the guide, run the following commands:" +msgstr "" + +#: ../../TRANSLATING.md:50 +msgid "" +"TODO: This section needs more work or to be replaced with a reference to " +"the CONTRIBUTING guide." +msgstr "" + +#: ../../TRANSLATING.md:52 +msgid "Starting a New Language Translation" +msgstr "" + +#: ../../TRANSLATING.md:54 +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:56 ../../TRANSLATING.md:222 +msgid "Important" +msgstr "" + +#: ../../TRANSLATING.md:57 +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:60 +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:62 +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:73 +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:76 +msgid "Preparing the Translation Files" +msgstr "" + +#: ../../TRANSLATING.md:78 +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:80 +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:86 +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:88 +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:90 +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:93 +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:96 +msgid "Working on a Translation" +msgstr "" + +#: ../../TRANSLATING.md:98 +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:100 +msgid "" +"In this folder you will find a set of `.po` files, corresponding to the " +"different sections of the guide:" +msgstr "" + +#: ../../TRANSLATING.md:116 +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:119 +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:121 +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:123 +msgid "" +"For example, to see the statistics for the Spanish translation, you would" +" run:" +msgstr "" + +#: ../../TRANSLATING.md:137 +msgid "What do these categories mean:" +msgstr "" + +#: ../../TRANSLATING.md:139 +msgid "" +"Translated strings are strings that have been translated into the target " +"language." +msgstr "" + +#: ../../TRANSLATING.md:140 +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:141 +msgid "Untranslated strings are strings that have not been translated yet." +msgstr "" + +#: ../../TRANSLATING.md:144 +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:147 +msgid "Editing the Translation Files" +msgstr "" + +#: ../../TRANSLATING.md:149 +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:151 +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:153 +msgid "" +"When you open a `.po` file, you will see a series of entries that look " +"like this:" +msgstr "" + +#: ../../TRANSLATING.md:163 +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:165 +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:175 +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:191 +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:193 +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:201 +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:218 +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:220 +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:223 +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:226 +msgid "Building the Translated Documentation" +msgstr "" + +#: ../../TRANSLATING.md:228 +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:234 +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:236 +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:238 +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:244 +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:246 +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:248 +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:250 +msgid "Submitting a PR for Your Contribution" +msgstr "" + +#: ../../TRANSLATING.md:252 +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:254 +msgid "You can follow these steps:" +msgstr "" + +#: ../../TRANSLATING.md:256 +msgid "" +"Build the translations of the guide with same parameters that will be " +"used during the release:" +msgstr "" + +#: ../../TRANSLATING.md:262 +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:263 +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:265 +msgid "If everything looks good, you can submit a PR with your changes." +msgstr "" + +#: ../../TRANSLATING.md:268 +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:271 +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:273 +msgid "TODO: This tagging could be automated with a GitHub Actions." +msgstr "" + +#: ../../TRANSLATING.md:275 +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:277 +msgid "The Review Process" +msgstr "" + +#: ../../TRANSLATING.md:279 +msgid "" +"The review process for a translation contribution is similar to the " +"review process for any other contribution to the guide." +msgstr "" + +#: ../../TRANSLATING.md:281 +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:283 +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:285 +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:287 +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:289 +msgid "The Release Process" +msgstr "" + +#: ../../TRANSLATING.md:291 +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:293 +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:295 +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 at: `https://www.pyopensci.org/python-package-guide/es/` when " +"it is published online." +msgstr "" + +#: ../../TRANSLATING.md:297 +msgid "Frequently Asked Questions (FAQ)" +msgstr "" + +#: ../../TRANSLATING.md:299 +msgid "How do I know which strings need to be translated?" +msgstr "" + +#: ../../TRANSLATING.md:301 +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:303 +msgid "What happens when a string has changed in the original English text?" +msgstr "" + +#: ../../TRANSLATING.md:305 +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:307 +msgid "How do I handle links in the translated text?" +msgstr "" + +#: ../../TRANSLATING.md:309 +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:311 +msgid "How do I handle formatting in the translated text?" +msgstr "" + +#: ../../TRANSLATING.md:313 +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:315 +msgid "How do I handle strings that are too long for a single line?" +msgstr "" + +#: ../../TRANSLATING.md:317 +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:330 +msgid "How do I translate images?" +msgstr "" + +#: ../../TRANSLATING.md:332 +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:334 +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:336 +msgid "" +"I am interested in translating the guide into a language that is not " +"listed. How can I get started?" +msgstr "" + +#: ../../TRANSLATING.md:338 +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:340 +msgid "How do I know when a translation is ready to be released?" +msgstr "" + +#: ../../TRANSLATING.md:342 +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:344 +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:346 +msgid "How can I get help with my translation?" +msgstr "" + +#: ../../TRANSLATING.md:348 +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:350 +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/pt/LC_MESSAGES/documentation.po b/locales/pt/LC_MESSAGES/documentation.po new file mode 100644 index 000000000..cee9fc7ee --- /dev/null +++ b/locales/pt/LC_MESSAGES/documentation.po @@ -0,0 +1,3405 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2026, pyOpenSci +# This file is distributed under the same license as the pyOpenSci Python +# Package Guide package. +# FIRST AUTHOR , 2026. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: pyOpenSci Python Package Guide \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-05-18 10:26-0700\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: pt\n" +"Language-Team: pt \n" +"Plural-Forms: nplurals=2; plural=(n != 1);\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.18.0\n" + +#: ../../documentation/glossary.md:7 +msgid "Python packaging glossary" +msgstr "" + +#: ../../documentation/glossary.md:9 +msgid "Core packaging" +msgstr "" + +#: ../../documentation/glossary.md +msgid "`__init__.py`" +msgstr "" + +#: ../../documentation/glossary.md:13 +msgid "" +"A special Python file that marks a directory as a Python package. When " +"Python sees this file, it knows the folder contains importable code. It " +"can either be empty or contain code that runs when the package is " +"imported." +msgstr "" + +#: ../../documentation/glossary.md:6 +msgid "API token" +msgstr "" + +#: ../../documentation/glossary.md:19 +msgid "" +"A secret key used to authenticate with PyPI or TestPyPI when publishing a" +" package. You generate one in your account settings and use it in place " +"of a password. **Treat it like a password and never share it or commit it" +" to version control**." +msgstr "" + +#: ../../documentation/glossary.md:12 +msgid "Build backend" +msgstr "" + +#: ../../documentation/glossary.md:25 +msgid "" +"The tool that does the actual work of building your package into " +"distribution files. In this guide, the build backend is Hatchling. You " +"specify it in your `pyproject.toml` file under `[build-system]`." +msgstr "" + +#: ../../documentation/glossary.md:29 +msgid "" +"You execute a build by running `hatch build`. Alternatively, you can run" +" `python -m build`. [Reference: official Python Packaging " +"documentation](https://packaging.python.org/en/latest/tutorials" +"/packaging-projects/#choosing-a-build-backend)" +msgstr "" + +#: ../../documentation/glossary.md:20 +msgid "Distribution files" +msgstr "" + +#: ../../documentation/glossary.md:33 +msgid "" +"The files you upload to PyPI so others can install your package. There " +"are two common types: a wheel (`.whl`) and a source distribution " +"(`.tar.gz`). See also `Wheel (.whl)` and `Source distribution (sdist)`." +msgstr "" + +#: ../../documentation/glossary.md:26 +msgid "Module" +msgstr "" + +#: ../../documentation/glossary.md:39 +msgid "" +"A single Python file (`.py`) containing code such as functions, classes, " +"or variables that can be imported. A package is made up of one or more " +"modules." +msgstr "" + +#: ../../documentation/glossary.md:31 +msgid "`pyproject.toml`" +msgstr "" + +#: ../../documentation/glossary.md:44 +msgid "" +"The configuration file at the root of your Python package. Written in " +"TOML format, it stores metadata such as name, version, authors, and " +"license. It can also configure tools such as Hatch, uv, and pytest. See " +"also [Make your Python package PyPI ready](../tutorials/pyproject-toml)." +msgstr "" + +#: ../../documentation/glossary.md:37 +msgid "Python package" +msgstr "" + +#: ../../documentation/glossary.md:50 +msgid "" +"A directory of Python code structured so it can be installed, imported, " +"and shared with others. A package includes at least an `__init__.py` file" +" and a `pyproject.toml` file. This is sometimes referred to as a " +"**regular package**." +msgstr "" + +#: ../../documentation/glossary.md:55 +msgid "" +"Info: You may hear the term **namespaced package** which is not really a " +"package at all but a container of subpackages. This is out of scope for " +"this guide. If interested, consult the [Python " +"documentation](https://docs.python.org/3/glossary.html#term-namespace-" +"package)." +msgstr "" + +#: ../../documentation/glossary.md:47 +msgid "PyPI / TestPyPI" +msgstr "" + +#: ../../documentation/glossary.md:60 +msgid "" +"PyPI (the Python Package Index) is the official repository where Python " +"packages are published and installed from. TestPyPI is a separate " +"practice environment used for learning and testing publishing workflows. " +"See [pypi.org](https://pypi.org) and " +"[test.pypi.org](https://test.pypi.org). See also [Publish your Python " +"package to PyPI](../tutorials/publish-pypi)." +msgstr "" + +#: ../../documentation/glossary.md:55 +msgid "Source distribution (sdist)" +msgstr "" + +#: ../../documentation/glossary.md:68 +msgid "" +"One of the two distribution file types for a Python package. The sdist " +"(`.tar.gz`) contains source code and project files. When someone installs" +" from an sdist, tools build the package locally first. See also [Publish " +"your Python package to PyPI](../tutorials/publish-pypi)." +msgstr "" + +#: ../../documentation/glossary.md:61 +msgid "TOML" +msgstr "" + +#: ../../documentation/glossary.md:74 +msgid "" +"Tom's Obvious Minimal Language, a simple format for configuration files. " +"TOML organizes data into tables such as `[project]` or `[tool.hatch]` and" +" arrays. `pyproject.toml` uses TOML." +msgstr "" + +#: ../../documentation/glossary.md:66 +msgid "Trusted publishing" +msgstr "" + +#: ../../documentation/glossary.md:79 +msgid "" +"A secure way to publish to PyPI using GitHub Actions instead of an API " +"token. Rather than storing a secret token, you configure PyPI to trust " +"your repository directly. See also [Setup Trusted Publishing for secure " +"and automated publishing via GitHub Actions](../tutorials/trusted-" +"publishing)." +msgstr "" + +#: ../../documentation/glossary.md:72 +msgid "Wheel (.whl)" +msgstr "" + +#: ../../documentation/glossary.md:85 +msgid "" +"The binary distribution type for a Python package. A wheel is a pre-built" +" binary format (`.whl`, a ZIP file) that installs directly without a " +"build step. For many pure Python packages, one wheel can work across " +"platforms. See also [Publish your Python package to PyPI](../tutorials" +"/publish-pypi)." +msgstr "" + +#: ../../documentation/glossary.md:92 +msgid "Tools" +msgstr "" + +#: ../../documentation/glossary.md +msgid "copier" +msgstr "" + +#: ../../documentation/glossary.md:96 +msgid "" +"A command-line tool for creating new projects from templates. In this " +"guide, you can use copier with the pyOpenSci package template to set up " +"structure, configuration, and tooling quickly. See " +"[copier.readthedocs.io](https://copier.readthedocs.io)." +msgstr "" + +#: ../../documentation/glossary.md:6 +msgid "coverage.py" +msgstr "" + +#: ../../documentation/glossary.md:102 +msgid "" +"A tool that measures how much of your code is exercised by tests, often " +"as a percentage. It shows which lines and branches are covered. See " +"[coverage.readthedocs.io](https://coverage.readthedocs.io)." +msgstr "" + +#: ../../documentation/glossary.md:11 +msgid "Hatch" +msgstr "" + +#: ../../documentation/glossary.md:107 +msgid "" +"A modern Python packaging and project management tool. In this guide, " +"Hatch is used to build packages, manage environments, run scripts, and " +"publish. Configuration lives in `pyproject.toml`. See " +"[hatch.pypa.io](https://hatch.pypa.io). See also [Get to know " +"Hatch](../tutorials/get-to-know-hatch)." +msgstr "" + +#: ../../documentation/glossary.md:18 +msgid "Hatchling" +msgstr "" + +#: ../../documentation/glossary.md:114 +msgid "" +"The build backend used by Hatch. When you run `python -m build` or `hatch" +" build`, Hatchling reads `pyproject.toml` and creates sdist and wheel " +"files. See " +"[hatch.pypa.io/latest/backend](https://hatch.pypa.io/latest/backend/)." +msgstr "" + +#: ../../documentation/glossary.md:24 +msgid "pip" +msgstr "" + +#: ../../documentation/glossary.md:120 +msgid "" +"Python's default package installer. You can use it to install packages " +"from PyPI into an environment with commands such as `pip install package-" +"name`. See [pip.pypa.io](https://pip.pypa.io)." +msgstr "" + +#: ../../documentation/glossary.md:29 +msgid "pytest" +msgstr "" + +#: ../../documentation/glossary.md:125 +msgid "" +"A widely used Python testing framework for discovering and running tests." +" In this guide, pytest often runs through Hatch scripts. See " +"[docs.pytest.org](https://docs.pytest.org)." +msgstr "" + +#: ../../documentation/glossary.md:34 +msgid "Ruff" +msgstr "" + +#: ../../documentation/glossary.md:130 +msgid "" +"A fast Python linter and formatter. It checks style and can automatically" +" fix many styling issues. See " +"[docs.astral.sh/ruff](https://docs.astral.sh/ruff)." +msgstr "" + +#: ../../documentation/glossary.md:39 +msgid "Sphinx" +msgstr "" + +#: ../../documentation/glossary.md:135 +msgid "" +"A documentation generator for Python projects. Sphinx reads docstrings " +"and documentation files to build a docs site. See [sphinx-" +"doc.org](https://www.sphinx-doc.org)." +msgstr "" + +#: ../../documentation/glossary.md:44 +msgid "Twine" +msgstr "" + +#: ../../documentation/glossary.md:140 +msgid "" +"A tool for securely uploading distribution files to PyPI or TestPyPI. See" +" [twine.readthedocs.io](https://twine.readthedocs.io)." +msgstr "" + +#: ../../documentation/glossary.md:48 +msgid "uv" +msgstr "" + +#: ../../documentation/glossary.md:144 +msgid "" +"A fast Python package and environment manager. In this guide, you can use" +" uv to manage dependencies and run commands in project environments. See " +"[docs.astral.sh/uv](https://docs.astral.sh/uv)." +msgstr "" + +#: ../../documentation/glossary.md:149 +msgid "Hatch-specific concepts" +msgstr "" + +#: ../../documentation/glossary.md +msgid "Hatch environment" +msgstr "" + +#: ../../documentation/glossary.md:153 +msgid "" +"An isolated Python environment managed by Hatch. You can define multiple " +"environments in `pyproject.toml` for testing, docs, builds, and style " +"checks, each with its own dependencies and scripts." +msgstr "" + +#: ../../documentation/glossary.md:5 +msgid "Script (Hatch)" +msgstr "" + +#: ../../documentation/glossary.md:158 +msgid "" +"A named command defined inside a Hatch environment in `pyproject.toml`. " +"Scripts provide shortcuts such as `hatch run build:check` and `hatch run " +"test:run`." +msgstr "" + +#: ../../documentation/glossary.md:10 +msgid "Task runner" +msgstr "" + +#: ../../documentation/glossary.md:163 +msgid "" +"A tool that automates repetitive development workflows. Hatch can " +"function as a task runner by letting you define scripts that run in " +"specific environments." +msgstr "" + +#: ../../documentation/glossary.md:168 +msgid "Development concepts" +msgstr "" + +#: ../../documentation/glossary.md +msgid "Code coverage" +msgstr "" + +#: ../../documentation/glossary.md:172 +msgid "" +"A measure of how much source code executes during tests, usually as a " +"percentage. High coverage does not guarantee no bugs, but low coverage " +"can indicate untested areas." +msgstr "" + +#: ../../documentation/glossary.md:5 +msgid "Dependencies" +msgstr "" + +#: ../../documentation/glossary.md:177 +msgid "" +"Other Python packages needed for your package to work. Common classes " +"include required dependencies, optional dependencies, and development " +"dependencies." +msgstr "" + +#: ../../documentation/glossary.md:10 +msgid "Docstring" +msgstr "" + +#: ../../documentation/glossary.md:182 +msgid "" +"A string at the top of a function, class, or module that describes " +"behavior, inputs, and outputs. Docstrings can be used by tools such as " +"Sphinx to generate API documentation." +msgstr "" + +#: ../../documentation/glossary.md:15 +msgid "End-to-end test" +msgstr "" + +#: ../../documentation/glossary.md:187 +msgid "" +"A test that simulates a complete user workflow from start to finish. In " +"scientific packages, tutorials executed during docs builds can serve as " +"end-to-end tests." +msgstr "" + +#: ../../documentation/glossary.md:20 +msgid "Integration test" +msgstr "" + +#: ../../documentation/glossary.md:192 +msgid "" +"A test that checks how multiple functions or components work together. " +"Unlike a unit test, it verifies behavior across a broader workflow." +msgstr "" + +#: ../../documentation/glossary.md:24 +msgid "Linting" +msgstr "" + +#: ../../documentation/glossary.md:196 +msgid "" +"Automatic checks for style issues, formatting problems, and potential " +"errors in code." +msgstr "" + +#: ../../documentation/glossary.md:28 +msgid "Unit test" +msgstr "" + +#: ../../documentation/glossary.md:200 +msgid "" +"A test that checks one function or method in isolation. Unit tests are " +"fast and help pinpoint where failures occur." +msgstr "" + +#: ../../documentation/glossary.md:32 +msgid "Version specifier / lower bound" +msgstr "" + +#: ../../documentation/glossary.md:204 +msgid "" +"A constraint on which dependency versions are accepted. For example, " +"`numpy>=1.24` sets a lower bound so versions older than 1.24 are not " +"used." +msgstr "" + +#: ../../documentation/glossary.md:209 +msgid "Git / GitHub" +msgstr "" + +#: ../../documentation/glossary.md +msgid "git" +msgstr "" + +#: ../../documentation/glossary.md:213 +msgid "A tool for version control." +msgstr "" + +#: ../../documentation/glossary.md:3 +msgid "GitHub" +msgstr "" + +#: ../../documentation/glossary.md:216 +msgid "" +"A service providing accounts and organizations to facilitate sharing " +"repositories." +msgstr "" + +#: ../../documentation/glossary.md:6 +msgid "GitHub Codespace" +msgstr "" + +#: ../../documentation/glossary.md:219 +msgid "" +"A cloud-based development environment that runs in a browser. See " +"[github.com/features/codespaces](https://github.com/features/codespaces)." +msgstr "" + +#: ../../documentation/glossary.md:10 +msgid "Scoped commit" +msgstr "" + +#: ../../documentation/glossary.md:223 +msgid "" +"A git commit that makes one focused change, such as one fix or one " +"feature update. Scoped commits improve reviewability and history clarity." +msgstr "" + +#: ../../documentation/glossary.md:228 +msgid "Documentation" +msgstr "" + +#: ../../documentation/glossary.md +msgid "Code of conduct" +msgstr "" + +#: ../../documentation/glossary.md:232 +msgid "" +"A document that sets expectations for how contributors and community " +"members treat one another in a project." +msgstr "" + +#: ../../documentation/glossary.md:4 +msgid "Contributing guide" +msgstr "" + +#: ../../documentation/glossary.md:236 +msgid "" +"A document, often `CONTRIBUTING.md`, that explains how others can " +"contribute, including setup steps, workflow, and code style." +msgstr "" + +#: ../../documentation/glossary.md:8 +msgid "MyST Markdown" +msgstr "" + +#: ../../documentation/glossary.md:240 +msgid "" +"Markedly Structured Text, a Markdown flavor that supports Sphinx " +"directives and roles. It allows Markdown-based docs while keeping Sphinx " +"features. See [myst-parser.readthedocs.io](https://myst-" +"parser.readthedocs.io)." +msgstr "" + +#: ../../documentation/glossary.md:14 +msgid "README" +msgstr "" + +#: ../../documentation/glossary.md:246 +msgid "" +"The front page of your package on GitHub and often on PyPI. A good README" +" explains purpose, installation, usage, and support options." +msgstr "" + +#: ../../documentation/glossary.md:250 +msgid "AI" +msgstr "" + +#: ../../documentation/glossary.md +msgid "Generative AI / LLM" +msgstr "" + +#: ../../documentation/glossary.md:254 +msgid "" +"Generative AI systems produce content such as text, code, or images. LLM " +"stands for Large Language Model, the technology behind tools such as " +"ChatGPT, GitHub Copilot, and Claude." +msgstr "" + +#: ../../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/what-is-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/sphinx-doc/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 and even for shares on collaboration platforms 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 Changelog](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/movingpandas/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 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/license). 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 +#, python-brace-format +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 +#, python-brace-format +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 strongly " +"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)." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:136 +msgid "" +"Additional resources on software citation The Turing Way has excellent " +"guides on this topic:" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:139 +msgid "" +"[CITATION.cff files](https://book.the-turing-" +"way.org/communication/citable/citable-cff) — detailed guide on creating " +"and maintaining citation files" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:140 +msgid "" +"[Software citation pathways](https://book.the-turing-way.org/pathways" +"/pathways-software-citation) — overview of how software citation works in" +" practice" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:142 +msgid "Citation.cff files: Making your software citable" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:144 +msgid "" +"A `CITATION.cff` file is a machine-readable file that provides citation " +"information for your software package. The \"cff\" stands for \"Citation " +"File Format,\" which is a standardized format for software citation " +"metadata." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:146 +msgid "What citation.cff files add to your repository" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:148 +msgid "" +"When you add a `CITATION.cff` file to your repository, GitHub " +"automatically detects it and displays a \"Cite this repository\" button. " +"This makes it easy for users to properly cite your software. The file " +"contains standardized citation information that tools and services can " +"automatically read and use. GitHub will generate both APA and BibTeX " +"citation formats for users." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:150 +msgid "How dates are tracked in citation.cff files" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:152 +msgid "" +"The citation file tracks important dates for your software. The `date-" +"released` field shows when the current version was released. The `date-" +"published` field shows when the software was first made available. You " +"also include a `version` field with the specific version number." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:154 +msgid "" +"You should update these dates with each new release so people cite the " +"correct version of your software." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:156 +msgid "Integration with Zenodo" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:158 +msgid "" +"Citation.cff files work well with Zenodo, which is a popular place to " +"store research software and get DOIs. When you create a Zenodo release, " +"it can automatically pull information from your citation file. This keeps" +" your citation information the same between GitHub and Zenodo. You can " +"also include your Zenodo DOI in the citation file. Each time you make a " +"new GitHub release, it can create a new Zenodo version with updated " +"citation information." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:161 +msgid "Here's a basic example of what a `CITATION.cff` file might look like:" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:177 +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" +"/unionai-" +"oss/pandera/workflows/CI%20Tests/badge.svg?branch=main)](https://github.com" +"/unionai-" +"oss/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://www.pyopensci.org/badges/peer-" +"reviewed.svg)](https://github.com/pyOpenSci/software-" +"submission/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/repository-files/readme-file-best-practices.md:178 +#, python-format +msgid "" +"[Standard Readme - Richard Littauer](https://github.com/RichardLitt" +"/standard-readme) [![standard-readme " +"compliant](https://img.shields.io/badge/readme%20style-standard-" +"brightgreen.svg)](https://github.com/RichardLitt/standard-readme)" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:178 +msgid "standard-readme compliant" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:179 +msgid "" +"[Standard Readme pre-commit hooks](https://github.com/tkoyama010" +"/standard-readme-pre-commit)" +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:2 +msgid "Document the code in your package's API using docstrings" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:4 +msgid "What is an API?" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:6 +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:10 +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:16 +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:18 +msgid "What is a docstring and how does it relate to documentation?" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:20 +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:23 +msgid "The docstring is thus important for:" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:25 +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:26 +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:29 +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:30 +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:31 +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:34 +msgid "Python package API documentation" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:36 +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:39 +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:43 +msgid "Explains what the function, method, attribute, or class does" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:44 +msgid "Defines the `type` inputs and outputs (ie. `string`, `int`, `np.array`)" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:45 +msgid "Explains the expected output `return` of the object, method or function." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:48 +msgid "Three Python docstring formats and why we like NumPy style" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:50 +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:53 +msgid "" +"[NumPy-style](https://numpydoc.readthedocs.io/en/latest/format.html" +"#docstring-standard)" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:54 +msgid "" +"[google style](https://sphinxcontrib-" +"napoleon.readthedocs.io/en/latest/example_google.html)" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:55 +msgid "" +"[reST style](https://sphinx-rtd-" +"tutorial.readthedocs.io/en/latest/docstrings.html)" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:59 +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:62 +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:63 +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:66 +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:71 +msgid "Docstring examples Better and Best" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:73 +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:107 +msgid "Best: a docstring with example use of the function" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:109 +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:160 +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:166 +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:171 +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:178 +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:186 +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:219 +msgid "Adding type hints to your docstrings" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:221 +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:236 +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:239 +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:243 +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:250 +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:258 +msgid "Why use type hints" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:260 +msgid "Type hints:" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:262 +msgid "Make development and debugging faster," +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:263 +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:264 +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:266 +msgid "You should consider adding type hinting to your code if:" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:268 +msgid "Your package performs data processing," +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:269 +msgid "You use functions that require complex inputs" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:270 +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:272 +msgid "Beware of too much type hinting" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:275 +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:277 +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:278 +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:281 +msgid "Gradually adding type hints" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:283 +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:287 +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/pt/LC_MESSAGES/index.po b/locales/pt/LC_MESSAGES/index.po new file mode 100644 index 000000000..d907811c2 --- /dev/null +++ b/locales/pt/LC_MESSAGES/index.po @@ -0,0 +1,500 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2026, pyOpenSci +# This file is distributed under the same license as the pyOpenSci Python +# Package Guide package. +# FIRST AUTHOR , 2026. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: pyOpenSci Python Package Guide \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-05-18 10:26-0700\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: pt\n" +"Language-Team: pt \n" +"Plural-Forms: nplurals=2; plural=(n != 1);\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.18.0\n" + +#: ../../index.md:257 +msgid "Tutorials" +msgstr "" + +#: ../../index.md:264 +msgid "Packaging" +msgstr "" + +#: ../../index.md:135 ../../index.md:272 +msgid "Documentation" +msgstr "" + +#: ../../index.md:175 ../../index.md:280 +msgid "Tests" +msgstr "" + +#: ../../index.md:280 +msgid "Testing" +msgstr "" + +#: ../../index.md:288 +msgid "Maintain" +msgstr "" + +#: ../../index.md:288 +msgid "Continuous Integration" +msgstr "" + +#: ../../index.md:296 +msgid "Glossary" +msgstr "" + +#: ../../index.md:296 +msgid "Reference" +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/python-package-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:45 +msgid "Todo" +msgstr "" + +#: ../../index.md:46 +msgid "TODO: change the navigation of docs to have a" +msgstr "" + +#: ../../index.md:48 +msgid "user documentation contributor / maintainer documentation" +msgstr "" + +#: ../../index.md:50 +msgid "development guide" +msgstr "" + +#: ../../index.md:51 +msgid "contributing guide" +msgstr "" + +#: ../../index.md:53 +msgid "Community docs" +msgstr "" + +#: ../../index.md:54 +msgid "readme, coc, license" +msgstr "" + +#: ../../index.md:56 +msgid "Publish your docs" +msgstr "" + +#: ../../index.md:59 +msgid "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:68 +msgid "✿ Create a Package Tutorials ✿" +msgstr "" + +#: ../../index.md:72 +msgid "[What is a Python package?](/tutorials/intro)" +msgstr "" + +#: ../../index.md:73 +msgid "[Create a Python package](/tutorials/create-python-package)" +msgstr "" + +#: ../../index.md:74 +msgid "[Publish your package to (test) PyPI](/tutorials/publish-pypi)" +msgstr "" + +#: ../../index.md:75 +msgid "[Publish your package to conda-forge](/tutorials/publish-conda-forge)" +msgstr "" + +#: ../../index.md:78 +msgid "✿ Package Metadata Tutorials ✿" +msgstr "" + +#: ../../index.md:82 +msgid "[How to add a README file](/tutorials/add-readme)" +msgstr "" + +#: ../../index.md:83 +msgid "" +"[How to add metadata to a pyproject.toml file for publication to " +"PyPI.](/tutorials/pyproject-toml.md)" +msgstr "" + +#: ../../index.md:86 +msgid "✿ Packaging Tool Tutorials ✿" +msgstr "" + +#: ../../index.md:90 +msgid "[Introduction to Hatch](/tutorials/get-to-know-hatch)" +msgstr "" + +#: ../../index.md:91 +msgid "[Run Python scripts using Hatch](/tutorials/run-python-scripts-hatch)" +msgstr "" + +#: ../../index.md:94 +msgid "✿ Reference Guides ✿" +msgstr "" + +#: ../../index.md:98 +msgid "[Command Line Reference Guide](/tutorials/command-line-reference)" +msgstr "" + +#: ../../index.md:102 +msgid "Python Packaging for Scientists" +msgstr "" + +#: ../../index.md:104 +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:111 +msgid "✨ Create your package ✨" +msgstr "" + +#: ../../index.md:115 +msgid "[Package file structure](/package-structure-code/python-package-structure)" +msgstr "" + +#: ../../index.md:116 +msgid "" +"[Package metadata / pyproject.toml](package-structure-code/pyproject-" +"toml-python-package-metadata.md)" +msgstr "" + +#: ../../index.md:117 +msgid "" +"[Build your package (sdist / wheel)](package-structure-code/python-" +"package-distribution-files-sdist-wheel.md)" +msgstr "" + +#: ../../index.md:118 +msgid "[Declare dependencies](package-structure-code/declare-dependencies.md)" +msgstr "" + +#: ../../index.md:119 +msgid "" +"[Navigate the packaging tool ecosystem](package-structure-code/python-" +"package-build-tools.md)" +msgstr "" + +#: ../../index.md:120 +msgid "" +"[Non pure Python builds](package-structure-code/complex-python-package-" +"builds.md)" +msgstr "" + +#: ../../index.md:123 +msgid "✨ Publish your package ✨" +msgstr "" + +#: ../../index.md:127 +msgid "" +"Gain a better understanding of the Python packaging ecosystem Learn about" +" best practices for:" +msgstr "" + +#: ../../index.md:130 +msgid "" +"[Package versioning & release](/package-structure-code/python-package-" +"versions.md)" +msgstr "" + +#: ../../index.md:131 +msgid "" +"[Publish to PyPI & Conda-forge](/package-structure-code/publish-python-" +"package-pypi-conda.md)" +msgstr "" + +#: ../../index.md:142 +msgid "✨ Write The Docs ✨" +msgstr "" + +#: ../../index.md:145 +msgid "" +"[Create documentation for your users](/documentation/write-user-" +"documentation/intro)" +msgstr "" + +#: ../../index.md:146 +msgid "" +"[Core files to include in your package repository](/documentation" +"/repository-files/intro)" +msgstr "" + +#: ../../index.md:147 +msgid "" +"[Write tutorials to show how your package is used](/documentation/write-" +"user-documentation/create-package-tutorials)" +msgstr "" + +#: ../../index.md:150 +msgid "✨ Developer Docs ✨" +msgstr "" + +#: ../../index.md:153 +msgid "" +"[Create documentation for collaborating developers](/documentation" +"/repository-files/contributing-file)" +msgstr "" + +#: ../../index.md:154 +msgid "" +"[Write a development guide](/documentation/repository-files/development-" +"guide)" +msgstr "" + +#: ../../index.md:157 +msgid "✨ Document For A Community ✨" +msgstr "" + +#: ../../index.md:160 +msgid "" +"[Writing a README file](/documentation/repository-files/readme-file-best-" +"practices)" +msgstr "" + +#: ../../index.md:161 +msgid "" +"[Set norms with a Code of Conduct](/documentation/repository-files/code-" +"of-conduct-file)" +msgstr "" + +#: ../../index.md:162 +msgid "[License your package](/documentation/repository-files/license-files)" +msgstr "" + +#: ../../index.md:165 +msgid "✨ Publish Your Docs ✨" +msgstr "" + +#: ../../index.md:168 +msgid "[How to publish your docs](/documentation/hosting-tools/intro)" +msgstr "" + +#: ../../index.md:169 +msgid "[Using Sphinx](/documentation/hosting-tools/intro)" +msgstr "" + +#: ../../index.md:170 +msgid "" +"[Markdown, MyST, and ReST](/documentation/hosting-tools/myst-markdown-" +"rst-doc-syntax)" +msgstr "" + +#: ../../index.md:171 +msgid "" +"[Host your docs on Read The Docs or GitHub Pages](/documentation/hosting-" +"tools/publish-documentation-online)" +msgstr "" + +#: ../../index.md:181 +msgid "✨ Tests for your Python package ✨" +msgstr "" + +#: ../../index.md:184 +msgid "[Intro to testing](tests/index.md)" +msgstr "" + +#: ../../index.md:185 +msgid "[Write tests](tests/write-tests)" +msgstr "" + +#: ../../index.md:186 +msgid "[Types of tests](tests/test-types)" +msgstr "" + +#: ../../index.md:189 +msgid "✨ Run your tests ✨" +msgstr "" + +#: ../../index.md:192 +msgid "[Run tests locally with Hatch](tests/run-tests)" +msgstr "" + +#: ../../index.md:193 +msgid "[Run tests with nox](tests/run-tests-nox)" +msgstr "" + +#: ../../index.md:194 +msgid "[Run tests in CI](tests/tests-ci)" +msgstr "" + +#: ../../index.md:198 +msgid "Contributing" +msgstr "" + +#: ../../index.md:205 +msgid "✨ Code style & Format ✨" +msgstr "" + +#: ../../index.md:208 +msgid "[Code style](package-structure-code/code-style-linting-format.md)" +msgstr "" + +#: ../../index.md:211 +msgid "✨ Want to contribute? ✨" +msgstr "" + +#: ../../index.md:216 +msgid "" +"We welcome contributions to this guide. Learn more about how you can " +"contribute." +msgstr "" + +#: ../../index.md:221 +msgid "A group of people building a pyramid with blocks" +msgstr "" + +#: ../../index.md:227 +msgid "A community-created guidebook" +msgstr "" + +#: ../../index.md:229 +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:232 +msgid "View guidebook contributors" +msgstr "" + +#: ../../index.md:240 +msgid "Who this guidebook is for" +msgstr "" + +#: ../../index.md:242 +msgid "" +"This guidebook is for anyone interested in learning more about Python " +"packaging. It is beginner-friendly and will provide:" +msgstr "" + +#: ../../index.md:244 +msgid "Beginning-to-end guidance on creating a Python package." +msgstr "" + +#: ../../index.md:245 +msgid "" +"Resources to help you navigate the Python packaging ecosystem of tools " +"and approaches to packaging." +msgstr "" + +#: ../../index.md:246 +msgid "" +"A curated list of resources to help you get your package into documented," +" usable and maintainable shape." +msgstr "" + +#: ../../index.md:248 +msgid "Where this guide is headed" +msgstr "" + +#: ../../index.md:250 +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:253 +msgid "" +"If you have questions about our peer review process or packaging in " +"general, you are welcome to use our [GitHub " +"Discussions](https://github.com/orgs/pyOpenSci/discussions)." +msgstr "" + +#: ../../index.md:255 +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/pt/LC_MESSAGES/maintain-automate.po b/locales/pt/LC_MESSAGES/maintain-automate.po new file mode 100644 index 000000000..3d87acc32 --- /dev/null +++ b/locales/pt/LC_MESSAGES/maintain-automate.po @@ -0,0 +1,1615 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2026, pyOpenSci +# This file is distributed under the same license as the pyOpenSci Python +# Package Guide package. +# FIRST AUTHOR , 2026. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: pyOpenSci Python Package Guide \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-05-18 10:26-0700\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: pt\n" +"Language-Team: pt \n" +"Plural-Forms: nplurals=2; plural=(n != 1);\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.18.0\n" + +#: ../../maintain-automate/ci.md:2 +msgid "" +"Continuous Integration and Continuous Deployment (CI/CD) For Python " +"Packages" +msgstr "" + +#: ../../maintain-automate/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 "" + +#: ../../maintain-automate/ci.md:12 +msgid "" +"**Continuous Integration (CI):** Automates the process of running tests, " +"code checks, and other workflows each time code is updated." +msgstr "" + +#: ../../maintain-automate/ci.md:14 +msgid "" +"**Continuous Deployment (CD):** Extends CI by allowing you to automate " +"publishing your package to PyPI, publishing your documentation, and more." +msgstr "" + +#: ../../maintain-automate/ci.md:18 +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 "" + +#: ../../maintain-automate/ci.md:23 +msgid "What is continuous integration?" +msgstr "" + +#: ../../maintain-automate/ci.md:25 +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 "" + +#: ../../maintain-automate/ci.md:28 +msgid "Running your test suite" +msgstr "" + +#: ../../maintain-automate/ci.md:29 +msgid "Running code checkers / linters / spellcheck" +msgstr "" + +#: ../../maintain-automate/ci.md:30 +msgid "Building your documentation" +msgstr "" + +#: ../../maintain-automate/ci.md:32 +msgid "" +"CI allows you to automate running workflows across a suite of " +"environments, including:" +msgstr "" + +#: ../../maintain-automate/ci.md:34 +msgid "environments containing different Python versions and" +msgstr "" + +#: ../../maintain-automate/ci.md:35 +msgid "different operating systems (Mac, Linux, Windows)." +msgstr "" + +#: ../../maintain-automate/ci.md:37 +msgid "What is continuous deployment (CD)?" +msgstr "" + +#: ../../maintain-automate/ci.md:39 +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 "" + +#: ../../maintain-automate/ci.md:41 +msgid "Automate publishing to PyPI" +msgstr "" + +#: ../../maintain-automate/ci.md:42 +msgid "Automate publishing your documentation to GitHub Pages or Read the Docs." +msgstr "" + +#: ../../maintain-automate/ci.md:44 +msgid "" +"It is also used once your conda-forge recipe is set up to keep your " +"package up to date on conda-forge." +msgstr "" + +#: ../../maintain-automate/ci.md:47 +msgid "Why use CI?" +msgstr "" + +#: ../../maintain-automate/ci.md:49 +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 "" + +#: ../../maintain-automate/ci.md:54 +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 "" + +#: ../../maintain-automate/ci.md:58 +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 "" + +#: ../../maintain-automate/ci.md:63 +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 "" + +#: ../../maintain-automate/ci.md:68 +msgid "" +"In the case of GitHub actions (which we will focus on here), CI workflows" +" are running on online servers that support GitHub." +msgstr "" + +#: ../../maintain-automate/ci.md:71 +msgid "CI/CD platforms" +msgstr "" + +#: ../../maintain-automate/ci.md:73 +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 "" + +#: ../../maintain-automate/ci.md:78 +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 "" + +#: ../../maintain-automate/ci.md:83 +msgid "If you aren't sure, use GitHub Actions" +msgstr "" + +#: ../../maintain-automate/ci.md:85 +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 "" + +#: ../../maintain-automate/ci.md:91 +msgid "Other platforms that you may run into" +msgstr "" + +#: ../../maintain-automate/ci.md:94 +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 "" + +#: ../../maintain-automate/ci.md:97 +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 "" + +#: ../../maintain-automate/ci.md:100 +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 "" + +#: ../../maintain-automate/ci.md:105 +msgid "Embrace automation" +msgstr "" + +#: ../../maintain-automate/ci.md:107 +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 "" + +#: ../../maintain-automate/environment-managers.md:2 +msgid "Environment Managers for Python Packaging" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:4 +msgid "Quick Decision Guide" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:6 +msgid "**Python-only project, want simplicity?** → venv + pip" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:7 +msgid "**Python-only, want speed?** → **uv** (recommended)" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:8 +msgid "**Installing CLI tools globally?** → pipx" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:9 +msgid "" +"**Need conda packages or cross-language dependencies?** → **pixi** " +"(recommended) or conda/mamba" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:10 +msgid "" +"**Creating a Python package?** → Use Hatch -- with UV as a dependency " +"manager" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:12 +msgid "" +"You can mix tools! For example, use **pipx** to install tools you use " +"often (at the command line) like Hatch, ruff or pre-commit, then use " +"**uv** within your projects for package and environment management." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:15 +msgid "Environment and package managers" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:17 +msgid "" +"Package and environment managers are important tools in your Python " +"packaging workflows. To make Your packaging experience when selecting a " +"tool will be easier if you understand the difference between the two." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:20 +msgid "" +"A **package manager** is used to install, update, and remove Python " +"packages (libraries and tools) and their dependencies in your " +"environment. When you use a package manager, you are often downloading " +"packages from a repository like PyPI (Python Package Index) or a local " +"repository like GitHub / GitLab." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:23 +msgid "" +"When you run `pip install numpy`, pip acts as a package manager and " +"installs numpy from PyPI. Pip's default repository when you install a " +"package is PyPI, but it can be used to install packages from other " +"repositories such as GitHub." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:26 +msgid "" +"An **environment manager** creates isolated spaces (environments) for " +"your Python projects. Each environment has its own Python installation " +"and its own installed packages. Using isolated environments for different" +" projects reduces the change of environment conflicts when using the same" +" environment across different projects with different dependencies." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:28 +msgid "" +"There are many tools listed below, but if you're short on time, you may " +"want to consider" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:30 +msgid "" +"Hatch combined with UV if you are managing a Python package. [Check out " +"our tutorials for more on this workflow.](create-pure-python-package)" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:31 +msgid "" +"Pixi or mamba as faster alternatives to conda if you are working in the " +"non-Pure Python packaging space." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:33 +msgid "Where environment managers save your environment" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:35 +msgid "" +"Environment managers save environments in different locations by default." +" For instance, `venv`, an environment manager that ships with Python, " +"saves an environment by default in your current working directory. UV has" +" the same native behavior. In contrast, conda and mamba save environments" +" in a global location, allowing you to access them easily across " +"projects." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:38 +msgid "" +"UV does have a global cache even tho its default behavior is to create an" +" environment in your current working directory." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:42 +msgid "Some tools do everything" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:44 +msgid "" +"Some modern tools handle both package installation and environment " +"management. For instance, UV, conda and mamba can be used to both create " +"environments, add dependencies, and build and install tools." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:46 +msgid "Comparison Table: pip ecosystem" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "Tool" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "Type" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "Language" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "Speed" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "Default Environment Location" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "Description" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "**pip**" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "Package manager" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +#: ../../maintain-automate/task-runners.md +msgid "Python" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "Slower" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "N/A (uses existing environment)" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "Python's standard package installer. pip also builds packages" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "**pipx**" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "Global (isolated per tool)" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "" +"Installs tools that you need to regularly use across projects such as " +"nox, pytest or ruff in a global location" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "**uv**" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "Both" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "Rust" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "Fastest" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "Current working directory" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "Fast package installer and environment creator" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "**venv**" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "Environment manager" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "Python's built-in environment creator" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "**virtualenv**" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "Moderate" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "Feature-rich alternative to venv" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:56 +msgid "Comparison Table: conda ecosystem" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "**conda**" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "Python/C++" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "Global (`~/anaconda3/envs/`)" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "Cross-language package and environment manager" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "**mamba**" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "C++" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "Faster" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "Faster drop-in replacement for conda" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "**pixi**" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "Current working directory (`.pixi/`)" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:37 +msgid "Modern conda-based tool with lock files" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:64 +msgid "" +"**Speed comparison:** Rust-based tools (uv, pixi) are significantly " +"faster when installing packages and resolving complex environments than " +"Python-based tools. Mamba is faster than conda but might be slower than " +"Rust-based alternatives such as Pixi." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:67 +msgid "Package Managers" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:69 +msgid "pip" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:71 +msgid "" +"Pip is Python's standard package installer. It is included with Python by" +" default." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:72 +msgid "" +"Pip is great for installing packages from PyPI and GitHub / GitLab into " +"existing environments." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:73 +msgid "" +"It is also great for development if you want to install your package " +"locally in editable mode." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:75 +#: ../../maintain-automate/environment-managers.md:87 +#: ../../maintain-automate/environment-managers.md:99 +#: ../../maintain-automate/environment-managers.md:127 +#: ../../maintain-automate/environment-managers.md:189 +#: ../../maintain-automate/environment-managers.md:211 +#: ../../maintain-automate/environment-managers.md:261 +#: ../../maintain-automate/environment-managers.md:280 +msgid "**Basic usage:**" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:81 +msgid "pipx" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:83 +msgid "" +"Pipx is can be used to install a tool that you need to use across " +"projects (like `riff`, `pytest`, `sphinx`, `nox`), globally." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:85 +msgid "" +"Why use it: You might use it to avoid reinstalling the same tool over and" +" over on your machine." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:93 +msgid "conda / mamba" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:95 +msgid "" +"Conda is a cross-language package manager that installs Python packages, " +"R packages, system libraries, and more. Mamba is a faster, drop-in " +"replacement for conda and we highly recommend mamba over conda if you are" +" still using conda." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:97 +msgid "" +"These tools are best for scientific computing projects and environments " +"that need non-Python dependencies (like C libraries, GDAL, or R " +"packages)." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:109 +msgid "Conda and mamba also function as environment managers - see below!" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:112 +#: ../../maintain-automate/index.md:46 +msgid "Environment Managers" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:114 +msgid "hatch for pure Python packaging" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:116 +#: ../../maintain-automate/environment-managers.md:204 +#: ../../maintain-automate/environment-managers.md:273 +msgid "pyOpenSci Recommends" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:118 +msgid "" +"We recommend **hatch** as a complete project management tool for Python " +"packaging. Hatch manages environments, builds packages, runs tests, and " +"handles publishing—all in one tool. It can use **uv** as its backend for " +"even faster operations." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:121 +msgid "" +"Hatch is a comprehensive modern Python project manager that handles " +"environments, package building, testing, and publishing. Hatch creates " +"isolated environments for different tasks (testing, docs, development). " +"Hatch uses UV under the hood to install Python, and can be set to use UV " +"to manage environment installations too." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:123 +msgid "" +"Hatch is best for Python package developers who want an all-in-one tool " +"that handles the entire packaging workflow from development to " +"publication." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:125 +msgid "[Check out our tutorial](create-pure-python-package)" +msgstr "" + +#: ../../maintain-automate/environment-managers.md +msgid "hatch (recommended)" +msgstr "" + +#: ../../maintain-automate/environment-managers.md +msgid "hatch with uv backend" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:160 +msgid "" +"Hatch acts as a task runner and can manage multiple environments that you" +" define. It also handles project and dependency installation, making it " +"ideal for package maintainers who want consistency across development " +"tasks." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:163 +msgid "venv" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:165 +msgid "" +"venv is Python's built-in environment creator (included with Python " +"3.3+). It is best for simple pure Python projects. Because venv ships " +"with Python, and it is used by Hatch, UV and other tools under the hood, " +"it is the most widely used tool." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:168 +msgid "Basic usage:" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:184 +msgid "virtualenv" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:186 +msgid "" +"virtualenv is a more feature-rich alternative to venv with better " +"performance and additional options. It's best for you if you need more " +"control over your environments." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:202 +msgid "uv" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:206 +msgid "" +"We recommend **uv** for fast, reliable Python package and environment " +"management. It's significantly faster than pip and easily handles both " +"installing packages and creating environments." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:209 +msgid "" +"UV is a fast, Rust-based tool that replaces both pip and venv. It " +"installs packages and creates virtual environments at lightning speed. UV" +" is best for any pure Python project. Pixi is better if are working in " +"the non-pure Python packaging space." +msgstr "" + +#: ../../maintain-automate/environment-managers.md +msgid "uv (recommended)" +msgstr "" + +#: ../../maintain-automate/environment-managers.md +msgid "venv + pip" +msgstr "" + +#: ../../maintain-automate/environment-managers.md +#: ../../maintain-automate/environment-managers.md:272 +msgid "pixi" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:256 +msgid "conda / mamba (as environment managers)" +msgstr "" + +#: ../../maintain-automate/environment-managers.md:258 +msgid "" +"Conda and mamba create isolated environments that can contain Python, R, " +"system libraries, and more. The conda ecosystem tools are best for " +"managing complex dependencies across languages or when you need specific " +"system libraries." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:275 +msgid "" +"For projects needing conda packages, we recommend **pixi** over " +"conda/mamba. It's faster, uses lock files for reproducibility, and works " +"cross-platform." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:278 +msgid "" +"Pixi is a modern, fast package and environment manager built on conda " +"ecosystems. Similar to UV, Pixi uses lock files for reproducible " +"environments. Pixi is best suited for scientific projects that require " +"conda packages, teams that require exact reproducibility, or cross-" +"platform development." +msgstr "" + +#: ../../maintain-automate/environment-managers.md:299 +msgid "" +"Pixi automatically creates a lock file (`pixi.lock`) ensuring everyone on" +" your team gets identical environments." +msgstr "" + +#: ../../maintain-automate/index.md:46 +msgid "What is CI?" +msgstr "" + +#: ../../maintain-automate/index.md:46 +msgid "Task runners" +msgstr "" + +#: ../../maintain-automate/index.md:46 +msgid "Maintain & Automate" +msgstr "" + +#: ../../maintain-automate/index.md:2 +msgid "Automate Workflows and Maintain Your Package" +msgstr "" + +#: ../../maintain-automate/index.md:4 +msgid "" +"Once you've [created your package](create-pure-python-package), " +"[published it](publish-pypi-tutorial), and set up a repository for it, " +"the next step is to automate development and maintenance workflows. " +"Automation makes maintaining your package easier, more robust, and more " +"secure. It also helps new contributors get started quickly without having" +" to manually set up complex development environments and testing " +"workflows." +msgstr "" + +#: ../../maintain-automate/index.md:11 +msgid "Why automate?" +msgstr "" + +#: ../../maintain-automate/index.md:13 +msgid "" +"When you automate repetitive tasks like running tests, checking code " +"style, and building documentation, you ensure that these important steps " +"happen consistently every time. This consistency helps you catch bugs " +"early, maintain code quality, and make it easier for others to contribute" +" to your package. Automation also saves you time—instead of remembering " +"and typing long command sequences, you can run everything with simple " +"commands or have workflows run automatically when you push code to " +"GitHub." +msgstr "" + +#: ../../maintain-automate/index.md:22 +msgid "What you'll learn" +msgstr "" + +#: ../../maintain-automate/index.md:24 +msgid "" +"This section will walk you through two key automation strategies for " +"Python packages:" +msgstr "" + +#: ../../maintain-automate/index.md:27 +msgid "" +"[**Task runners**](task-runners-intro) help you automate common " +"development tasks locally— things like running tests, building " +"documentation, formatting code, and checking for errors. Instead of " +"typing out long command sequences every time, you define tasks once and " +"run them with simple commands. Task runners like Hatch and Nox also " +"manage isolated environments for different workflows, ensuring you have " +"the right dependencies for each task." +msgstr "" + +#: ../../maintain-automate/index.md:35 +msgid "" +"[**Continuous Integration (CI)**](ci-cd) takes automation further by " +"running your tests and checks automatically every time code is pushed to " +"GitHub or when someone opens a pull request. CI ensures that all changes " +"are tested across different Python versions and operating systems before " +"they're merged. You can also use Continuous Deployment (CD) to automate " +"publishing your package to PyPI and deploying your documentation." +msgstr "" + +#: ../../maintain-automate/index.md:42 +msgid "" +"Together, task runners and CI/CD create a robust development workflow " +"that makes your package easier to maintain and more welcoming to " +"contributors." +msgstr "" + +#: ../../maintain-automate/task-runners.md:2 +msgid "Task Runners for Python Packaging" +msgstr "" + +#: ../../maintain-automate/task-runners.md:4 +msgid "What is a Task Runner?" +msgstr "" + +#: ../../maintain-automate/task-runners.md:6 +msgid "" +"A task runner is a tool that automates repetitive development workflows. " +"Instead of typing out long command sequences every time you need to test " +"your code, build documentation, or check your package, you define these " +"tasks once and run them with simple commands." +msgstr "" + +#: ../../maintain-automate/task-runners.md:11 +msgid "For example, rather than running:" +msgstr "" + +#: ../../maintain-automate/task-runners.md:19 +msgid "You can define a task and run:" +msgstr "" + +#: ../../maintain-automate/task-runners.md:25 +msgid "" +"Most modern task runners also include environment management features " +"that make it quick and easy to run tasks. Task runners ensure that " +"workflows are executed consistently every time, whether you're running " +"them on your laptop or in continuous integration, and they also make it " +"easier for contributors to recreate the same workflows in their local " +"environments." +msgstr "" + +#: ../../maintain-automate/task-runners.md:32 +msgid "Benefits of task runners" +msgstr "" + +#: ../../maintain-automate/task-runners.md:34 +msgid "" +"Task runners provide several benefits for package development. When you " +"use a task runner, everyone on your team runs tasks the same way, " +"reducing environment-specific issues and \"works on my machine\" " +"problems. Complex multi-step processes become single commands, so " +"contributors don't need to memorize or look up lengthy command sequences." +msgstr "" + +#: ../../maintain-automate/task-runners.md:41 +msgid "" +"Many task runners also create isolated environments for different " +"workflows, ensuring the right dependencies are available for each task " +"without conflicts. This means your tasks run the same way locally and in " +"continuous integration, making debugging easier and builds more reliable." +msgstr "" + +#: ../../maintain-automate/task-runners.md:47 +msgid "Two types of task runners" +msgstr "" + +#: ../../maintain-automate/task-runners.md:49 +msgid "" +"The most common task runners used in the Python ecosystem fall into two " +"categories:" +msgstr "" + +#: ../../maintain-automate/task-runners.md:51 +msgid "Environment + command managers" +msgstr "" + +#: ../../maintain-automate/task-runners.md:53 +msgid "" +"You can use these to both create custom isolated environments and also to" +" run your tasks." +msgstr "" + +#: ../../maintain-automate/task-runners.md:55 +msgid "" +"**[Hatch](https://hatch.pypa.io/):** Hatch is an all-in-one package " +"management tool that includes a built-in task runner. It uses a " +"declarative TOML configuration in your `pyproject.toml` file, which means" +" everything related to your package—metadata, dependencies, and " +"tasks—lives in one place. Hatch also integrates with UV for fast " +"environment creation." +msgstr "" + +#: ../../maintain-automate/task-runners.md:56 +msgid "" +"**[Nox](https://nox.thea.codes/):** Nox is a flexible Python-based task " +"runner that uses a code-based (imperative) configuration approach. You " +"write Python functions to define your tasks in a `noxfile.py`, which " +"gives you maximum flexibility for complex testing scenarios and " +"conditional logic. It's especially popular in the Scientific Python " +"ecosystem." +msgstr "" + +#: ../../maintain-automate/task-runners.md:57 +msgid "" +"**[Tox](https://tox.wiki/):** Tox is a mature declarative tool that uses " +"INI or TOML configuration files. It's particularly well-suited for " +"testing across multiple Python versions and dependency combinations, and " +"has been a standard in the Python community for years." +msgstr "" + +#: ../../maintain-automate/task-runners.md:59 +msgid "Command-only tools" +msgstr "" + +#: ../../maintain-automate/task-runners.md:61 +msgid "These tools execute your commands but don't manage environments." +msgstr "" + +#: ../../maintain-automate/task-runners.md:63 +msgid "" +"**[Make](https://www.gnu.org/software/make/):** Make is a traditional " +"build automation tool that uses Makefiles. It's widely known and " +"available on most systems, making it a good choice for simple task " +"automation when you don't need Python-specific features. However, it can " +"have cross-platform compatibility issues, especially on Windows." +msgstr "" + +#: ../../maintain-automate/task-runners.md:64 +msgid "" +"**[Just](https://just.systems/):** Just is a modern command runner " +"written in Rust with simple, Make-like syntax. It's fast, cross-platform," +" and easy to learn, making it a good lightweight alternative when you " +"need basic task running without environment management." +msgstr "" + +#: ../../maintain-automate/task-runners.md:66 +msgid "" +"Generally the two task runners that pyOpenSci suggests and uses are " +"[Nox](https://nox.thea.codes/en/stable/) and [Hatch (also a package " +"management tool)](https://hatch.pypa.io/latest/). Below, you will learn " +"about the differences between all of the tools and can make a decision " +"for yourself depending on your needs." +msgstr "" + +#: ../../maintain-automate/task-runners.md:71 +msgid "pyOpenSci recommends: Hatch and Nox" +msgstr "" + +#: ../../maintain-automate/task-runners.md:73 +msgid "" +"At pyOpenSci, the recommendation is **Hatch** for Python package " +"development. Hatch also includes a task and environment system feature. " +"Using Hatch means you don't need to setup another tool like Nox." +msgstr "" + +#: ../../maintain-automate/task-runners.md:77 +msgid "" +"However, **Nox** is also an excellent choice, particularly if you need " +"complex testing, build or workflow logic." +msgstr "" + +#: ../../maintain-automate/task-runners.md:80 +msgid "" +"You'll find many of the pyOpenSci documentation repositories use Nox to " +"automate workflows such as building and testing documentation." +msgstr "" + +#: ../../maintain-automate/task-runners.md:83 +msgid "Why use Hatch?" +msgstr "" + +#: ../../maintain-automate/task-runners.md:85 +msgid "" +"Hatch is an all-in-one tool that helps you manage metadata, dependencies," +" build configuration, and tasks together in `pyproject.toml`. Using " +"Hatch, everything related to your package lives in one place. It combines" +" packaging (building and publishing) with everyday development tasks like" +" testing, docs, and formatting, making workflows easier to run and share." +" Hatch also integrates with UV making it extremely fast. Finally, Hatch " +"follows modern packaging practices (for example, PEP 621), so your " +"project stays aligned with community standards." +msgstr "" + +#: ../../maintain-automate/task-runners.md:95 +msgid "Why use Nox?" +msgstr "" + +#: ../../maintain-automate/task-runners.md:97 +msgid "" +"Python-based configuration gives Nox maximum flexibility, making it easy " +"to express complex logic and conditionals directly. Because sessions are " +"written in Python, they are explicit and easy to inspect and debug. Nox " +"is particularly powerful for handling complex test and build scenarios " +"that some packages require." +msgstr "" + +#: ../../maintain-automate/task-runners.md:103 +msgid "Declarative vs. imperative configuration" +msgstr "" + +#: ../../maintain-automate/task-runners.md:105 +msgid "An important distinction between these tools is how you configure them:" +msgstr "" + +#: ../../maintain-automate/task-runners.md:107 +msgid "" +"Hatch is a **Declarative tool**. This means it uses a configuration file " +"where you specify *what* you want. See the example below:" +msgstr "" + +#: ../../maintain-automate/task-runners.md:119 +msgid "" +"Nox uses an **Imperative** approach to defining workflows. With Nox, you " +"write Python code that defines how to perform a task. An example of a Nox" +" function (which would live in a separate noxfile.py file) is shown " +"below:" +msgstr "" + +#: ../../maintain-automate/task-runners.md:132 +msgid "Trade-offs: declarative vs. imperative" +msgstr "" + +#: ../../maintain-automate/task-runners.md:134 +msgid "" +"**Declarative (Hatch, Tox):** Simpler syntax, easier to read and " +"maintain. Might be slightly less flexible for complex logic (this is user" +" dependent)." +msgstr "" + +#: ../../maintain-automate/task-runners.md:137 +msgid "" +"**Imperative (Nox):** You can easily include complex logic and " +"conditionals. Because it uses Python, it might be more familiar to you!" +msgstr "" + +#: ../../maintain-automate/task-runners.md:141 +msgid "" +"Neither approach is inherently better—it depends on your needs and " +"preferences. Projects with complex testing scenarios may benefit from " +"Nox's flexibility, while projects wanting simple, standardized workflows " +"may prefer the clarity of declarative configuration." +msgstr "" + +#: ../../maintain-automate/task-runners.md:146 +msgid "An overview of the core task runners tools that you will find in" +msgstr "" + +#: ../../maintain-automate/task-runners.md:147 +msgid "the Python ecosystem" +msgstr "" + +#: ../../maintain-automate/task-runners.md:149 +msgid "Comparison table" +msgstr "" + +#: ../../maintain-automate/task-runners.md:151 +msgid "" +"Below you will see a comparison of features associated with each tool. " +"Each tool is then described in a bit more detail just in case you want a " +"better lay of the land." +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "Feature" +msgstr "" + +#: ../../maintain-automate/task-runners.md +#: ../../maintain-automate/task-runners.md:167 +msgid "Hatch" +msgstr "" + +#: ../../maintain-automate/task-runners.md +#: ../../maintain-automate/task-runners.md:223 +msgid "Nox" +msgstr "" + +#: ../../maintain-automate/task-runners.md +#: ../../maintain-automate/task-runners.md:275 +msgid "Tox" +msgstr "" + +#: ../../maintain-automate/task-runners.md +#: ../../maintain-automate/task-runners.md:321 +msgid "Make" +msgstr "" + +#: ../../maintain-automate/task-runners.md +#: ../../maintain-automate/task-runners.md:360 +msgid "Just" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "**Configuration**" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "pyproject.toml" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "noxfile.py" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "tox.ini" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "Makefile" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "justfile" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "**Configuration Style**" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "Declarative" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "Imperative" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "**Language**" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "TOML" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "INI/TOML" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "Make syntax" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "Just syntax" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "**Python-specific**" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "Yes" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "No" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "**Environment Management**" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "**Matrix Testing**" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "**Packaging Integration**" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "**Cross-platform**" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "Limited" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "**Best For**" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "Complete package development" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "Complex testing workflows and other builds" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "Legacy projects, standard testing" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "Simple tasks" +msgstr "" + +#: ../../maintain-automate/task-runners.md +msgid "Simple commands" +msgstr "" + +#: ../../maintain-automate/task-runners.md:169 +msgid "" +"[Hatch](https://hatch.pypa.io/) is a modern, all-in-one packaging and " +"task automation tool that simplifies Python package development by " +"handling everything from building and publishing to running tests and " +"formatting code. Hatch is what we use [in our packaging tutorials found " +"in this guidebook](packaging-101)." +msgstr "" + +#: ../../maintain-automate/task-runners.md:174 +msgid "Why we like Hatch" +msgstr "" + +#: ../../maintain-automate/task-runners.md:176 +msgid "" +"Hatch stands out because it's a single tool that handles both packaging " +"AND task running. Instead of juggling multiple tools, you configure " +"everything in your `pyproject.toml` file—no extra configuration files " +"needed. Hatch creates isolated environments for different tasks (like " +"testing or building docs) and integrates with UV for extremely fast " +"environment setup. It uses a declarative, clean syntax that's easy to " +"read and maintain, and it supports matrix testing so you can easily test " +"your package across multiple Python versions." +msgstr "" + +#: ../../maintain-automate/task-runners.md:185 +msgid "When to use Hatch" +msgstr "" + +#: ../../maintain-automate/task-runners.md:187 +msgid "" +"Hatch is ideal for complete package development workflows. You can use it" +" for testing across Python versions, building documentation, running code" +" formatters and linters, and building and publishing your package to " +"PyPI. If you want a modern, all-in-one solution that follows current " +"Python packaging standards (like PEP 621), Hatch is an excellent choice." +msgstr "" + +#: ../../maintain-automate/task-runners.md:194 +#: ../../maintain-automate/task-runners.md:251 +#: ../../maintain-automate/task-runners.md:299 +#: ../../maintain-automate/task-runners.md:344 +#: ../../maintain-automate/task-runners.md:383 +msgid "Example configuration" +msgstr "" + +#: ../../maintain-automate/task-runners.md:196 +msgid "" +"Below is an example of how you'd set up a test environment in Hatch. This" +" configuration creates a `test` environment with pytest and pytest-cov " +"installed, defines a `run` script to execute your tests, and sets up " +"matrix testing to run tests on Python 3.10, 3.11, and 3.12:" +msgstr "" + +#: ../../maintain-automate/task-runners.md:217 +#: ../../maintain-automate/task-runners.md:269 +#: ../../maintain-automate/task-runners.md:315 +#: ../../maintain-automate/task-runners.md:356 +#: ../../maintain-automate/task-runners.md:396 +msgid "You would run the above in your terminal using:" +msgstr "" + +#: ../../maintain-automate/task-runners.md:219 +msgid "`hatch run test:run`" +msgstr "" + +#: ../../maintain-automate/task-runners.md:221 +msgid "**Learn more:** [Hatch documentation](https://hatch.pypa.io/)" +msgstr "" + +#: ../../maintain-automate/task-runners.md:225 +msgid "" +"[Nox](https://nox.thea.codes/) is a Python-based automation toolkit " +"focused on testing across environments. It uses a code-based (imperative)" +" configuration approach that gives you maximum flexibility for complex " +"testing workflows." +msgstr "" + +#: ../../maintain-automate/task-runners.md:230 +msgid "Why we like Nox" +msgstr "" + +#: ../../maintain-automate/task-runners.md:232 +msgid "" +"Nox stands out because it uses Python code to define your tasks, which " +"means you can include complex logic and conditionals directly in your " +"automation workflows. Because sessions are written in Python, they're " +"explicit, easy to inspect, and straightforward to debug. Nox is " +"particularly powerful for handling complex test and build scenarios that " +"some packages require, and it's especially popular in the Scientific " +"Python ecosystem. You'll find many pyOpenSci documentation repositories " +"use Nox to automate workflows such as building and testing documentation." +msgstr "" + +#: ../../maintain-automate/task-runners.md:242 +msgid "When to use Nox" +msgstr "" + +#: ../../maintain-automate/task-runners.md:244 +msgid "" +"Nox is ideal when you need complex testing scenarios with conditional " +"logic or when you prefer Python-based configuration over declarative " +"formats. It's excellent for testing across Python versions and managing " +"multiple testing environments. If packaging is handled separately and you" +" want maximum flexibility in your task automation, Nox is a great choice." +msgstr "" + +#: ../../maintain-automate/task-runners.md:253 +msgid "" +"Below is an example of a Nox session that runs tests across multiple " +"Python versions. The `@nox.session` decorator defines a session (similar " +"to a task), and you specify which Python versions to test with. Nox will " +"create isolated environments for each version and run your tests:" +msgstr "" + +#: ../../maintain-automate/task-runners.md:271 +msgid "`nox -s tests`" +msgstr "" + +#: ../../maintain-automate/task-runners.md:273 +msgid "**Learn more:** [Nox documentation](https://nox.thea.codes/)" +msgstr "" + +#: ../../maintain-automate/task-runners.md:277 +msgid "" +"[Tox](https://tox.wiki/) is a mature automation tool for testing in " +"multiple environments. It uses declarative configuration and has been a " +"standard in the Python community for years." +msgstr "" + +#: ../../maintain-automate/task-runners.md:281 +msgid "Why people use Tox" +msgstr "" + +#: ../../maintain-automate/task-runners.md:283 +msgid "" +"Tox is mature and stable, with a long history in the Python ecosystem. It" +" uses declarative configuration (traditionally INI format, though TOML " +"support was added recently) and is particularly good for testing across " +"Python versions and dependency sets. Many projects use Tox because it " +"integrates well with CI/CD systems and has a robust plugin ecosystem." +msgstr "" + +#: ../../maintain-automate/task-runners.md:290 +msgid "When to use Tox" +msgstr "" + +#: ../../maintain-automate/task-runners.md:292 +msgid "" +"Tox is ideal if you're maintaining a legacy project that already uses it," +" or if you have existing `tox.ini` configuration you want to preserve. " +"It's also a good choice if you need specific Tox plugins or prefer " +"declarative configuration separate from your packaging tools. However, " +"keep in mind that Tox can be slower than modern alternatives like Hatch." +msgstr "" + +#: ../../maintain-automate/task-runners.md:301 +msgid "" +"Below is an example of a Tox configuration that runs tests across " +"multiple Python versions. The `envlist` specifies which Python versions " +"to test, and the `testenv` section defines what to install and run:" +msgstr "" + +#: ../../maintain-automate/task-runners.md:317 +msgid "" +"`tox` (runs all environments) or `tox -e py310` (runs a specific " +"environment)" +msgstr "" + +#: ../../maintain-automate/task-runners.md:319 +msgid "**Learn more:** [Tox documentation](https://tox.wiki/)" +msgstr "" + +#: ../../maintain-automate/task-runners.md:323 +msgid "" +"[Make](https://www.gnu.org/software/make/) is a traditional build " +"automation tool that uses Makefiles. It's been around since the 1970s and" +" is widely used across many programming languages." +msgstr "" + +#: ../../maintain-automate/task-runners.md:327 +msgid "Why people use Make" +msgstr "" + +#: ../../maintain-automate/task-runners.md:329 +msgid "" +"Make is widely known and available on most systems, making it a familiar " +"choice for many developers. It has simple syntax for basic tasks and " +"executes very quickly. Because it's not Python-specific, you can use it " +"to coordinate tasks across different languages in the same project." +msgstr "" + +#: ../../maintain-automate/task-runners.md:335 +msgid "When to use Make" +msgstr "" + +#: ../../maintain-automate/task-runners.md:337 +msgid "" +"Make is best for simple task automation when you don't need Python-" +"specific features or environment management. It's a good lightweight " +"option if you want something fast and universally available. However, be " +"aware that Make can have cross-platform compatibility issues, especially " +"on Windows, and you'll need to handle Python environment management " +"separately." +msgstr "" + +#: ../../maintain-automate/task-runners.md:346 +msgid "" +"Below is an example of a simple Makefile with tasks for testing and " +"building documentation:" +msgstr "" + +#: ../../maintain-automate/task-runners.md:358 +msgid "`make test` or `make docs`" +msgstr "" + +#: ../../maintain-automate/task-runners.md:362 +msgid "" +"[Just](https://just.systems/) is a modern command runner written in Rust " +"that offers a simpler, more user-friendly alternative to Make." +msgstr "" + +#: ../../maintain-automate/task-runners.md:365 +msgid "Why people use Just" +msgstr "" + +#: ../../maintain-automate/task-runners.md:367 +msgid "" +"Just has simple, Make-like syntax but with better error messages and more" +" intuitive behavior. It's fast, truly cross-platform (unlike Make), and " +"easy to learn. The tool is written in Rust, which makes it very " +"performant, and it avoids many of the quirks and gotchas that Make has " +"accumulated over decades." +msgstr "" + +#: ../../maintain-automate/task-runners.md:373 +msgid "When to use Just" +msgstr "" + +#: ../../maintain-automate/task-runners.md:375 +msgid "" +"Just is ideal when you need a lightweight command runner for simple tasks" +" and don't require Python-specific features or environment management. " +"It's a great choice if you want something faster and more modern than " +"Make, with better cross-platform support. However, keep in mind that Just" +" requires separate installation and has less integration with the Python " +"packaging ecosystem compared to tools like Hatch or Nox." +msgstr "" + +#: ../../maintain-automate/task-runners.md:385 +msgid "" +"Below is an example of a justfile with tasks for testing and building " +"documentation:" +msgstr "" + +#: ../../maintain-automate/task-runners.md:398 +msgid "`just test` or `just docs`" +msgstr "" + +#: ../../maintain-automate/task-runners.md:400 +msgid "**Learn more:** [Just documentation](https://just.systems/)" +msgstr "" + +#: ../../maintain-automate/task-runners.md:402 +msgid "Choosing the right task runner" +msgstr "" + +#: ../../maintain-automate/task-runners.md:404 +msgid "**Choose Hatch if:**" +msgstr "" + +#: ../../maintain-automate/task-runners.md:406 +msgid "You're building a Python package" +msgstr "" + +#: ../../maintain-automate/task-runners.md:407 +msgid "You want an all-in-one tool" +msgstr "" + +#: ../../maintain-automate/task-runners.md:408 +msgid "You prefer configuration in pyproject.toml" +msgstr "" + +#: ../../maintain-automate/task-runners.md:409 +msgid "You want fast environment management" +msgstr "" + +#: ../../maintain-automate/task-runners.md:410 +msgid "You prefer declarative configuration" +msgstr "" + +#: ../../maintain-automate/task-runners.md:412 +msgid "**Choose Nox if:**" +msgstr "" + +#: ../../maintain-automate/task-runners.md:414 +msgid "You need complex testing scenarios with conditional logic" +msgstr "" + +#: ../../maintain-automate/task-runners.md:415 +msgid "You prefer Python-based, imperative configuration" +msgstr "" + +#: ../../maintain-automate/task-runners.md:416 +msgid "You're working in the Scientific Python ecosystem" +msgstr "" + +#: ../../maintain-automate/task-runners.md:417 +msgid "Packaging is handled separately" +msgstr "" + +#: ../../maintain-automate/task-runners.md:418 +msgid "You want maximum flexibility" +msgstr "" + +#: ../../maintain-automate/task-runners.md:420 +msgid "**Choose Tox if:**" +msgstr "" + +#: ../../maintain-automate/task-runners.md:422 +msgid "You're maintaining a legacy project already using it" +msgstr "" + +#: ../../maintain-automate/task-runners.md:423 +msgid "You have existing tox.ini configuration" +msgstr "" + +#: ../../maintain-automate/task-runners.md:424 +msgid "You need specific tox plugins" +msgstr "" + +#: ../../maintain-automate/task-runners.md:425 +msgid "You prefer declarative configuration separate from packaging" +msgstr "" + +#: ../../maintain-automate/task-runners.md:427 +msgid "**Choose Make or Just if:**" +msgstr "" + +#: ../../maintain-automate/task-runners.md:429 +msgid "You need a lightweight command runner" +msgstr "" + +#: ../../maintain-automate/task-runners.md:430 +msgid "You're not doing Python-specific workflows" +msgstr "" + +#: ../../maintain-automate/task-runners.md:431 +msgid "You want something simple and fast" +msgstr "" + +#: ../../maintain-automate/task-runners.md:432 +msgid "You don't need environment management" +msgstr "" + +#: ../../maintain-automate/task-runners.md:434 +msgid "Next steps" +msgstr "" + +#: ../../maintain-automate/task-runners.md:436 +msgid "" +"Learn how to use [Hatch " +"environments](https://hatch.pypa.io/latest/tutorials/environment/basic-" +"usage/)" +msgstr "" + +#: ../../maintain-automate/task-runners.md:437 +msgid "" +"[Create a package using the Python package tutorial.](create-pure-python-" +"package)" +msgstr "" + +#: ../../maintain-automate/task-runners.md:438 +msgid "" +"Explore and use the [pyOpenSci package " +"template](https://github.com/pyOpenSci/pyos-package-template) with pre-" +"configured Hatch tasks" +msgstr "" + +#: ../../maintain-automate/task-runners.md:441 +msgid "" +"Read the [Scientific Python development guide on task " +"runners](https://learn.scientific-python.org/development/guides/tasks/). " +"This guide is excellent if you plan to use nox as your task runner as it " +"has lots of examples that you can follow." +msgstr "" diff --git a/locales/pt/LC_MESSAGES/package-structure-code.po b/locales/pt/LC_MESSAGES/package-structure-code.po new file mode 100644 index 000000000..ab3948761 --- /dev/null +++ b/locales/pt/LC_MESSAGES/package-structure-code.po @@ -0,0 +1,5444 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2026, pyOpenSci +# This file is distributed under the same license as the pyOpenSci Python +# Package Guide package. +# FIRST AUTHOR , 2026. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: pyOpenSci Python Package Guide \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-05-18 10:26-0700\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: pt\n" +"Language-Team: pt \n" +"Plural-Forms: nplurals=2; plural=(n != 1);\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.18.0\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:39 +msgid "Use a code format tool (or tools) to make your life easier" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:41 +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:47 +msgid "Setting up a code format suite of tools will:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:49 +msgid "Save you and your maintainer team time in fixing PEP 8 inconsistencies." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:50 +msgid "Ensure that format and style is consistent across your entire code-base." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:51 +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:53 +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:55 +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:58 +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:61 +msgid "Linting vs. format and style" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:63 +msgid "Before we dive in let's get a few definitions out of the way." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:65 +msgid "Code linting" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:67 +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:72 +msgid "Code formatters (and stylers)" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:74 +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:78 +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:82 +msgid "You will learn more about Black below." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:84 +msgid "Code linting, formatting and styling tools" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:87 +msgid "Black" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:89 +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:95 +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:96 +msgid "Black will not adjust line length in your comments or docstrings." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:97 +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:100 +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:104 +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:108 +msgid "Flake8" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:110 +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:114 +msgid "flake8 will:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:116 +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:117 +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:119 +msgid "" +"Flake8 also flags unused imports and unused declared variables in your " +"modules." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:122 +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:126 +msgid "The line length standard for PEP 8 is 79 characters." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:128 +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:143 +msgid "Isort" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:145 +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:149 +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:151 +msgid "Imports should be grouped in the following order:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:153 +msgid "Standard library imports." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:154 +msgid "Related third party imports." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:155 +msgid "Local application/library specific imports." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:157 +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:160 +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:165 +msgid "Example application of isort" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:167 +msgid "Code imports before `isort` is run:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:169 +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:179 +msgid "From the project root, run:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:185 +msgid "Python file `temporal.py` imports after `isort` has been run" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:193 +msgid "Ruff" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:195 +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:201 +msgid "" +"`ruff` has some interesting features that distinguish it from other " +"linters:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:203 +msgid "Linter configuration in `pyproject.toml`" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:204 +msgid "Several hundred rules included, many of which are automatically fixable" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:205 +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:206 +msgid "" +"Fast execution time, makes a quick feedback loop possible even on large " +"projects." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:208 +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:216 +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:224 +msgid "How to use code formatter in your local workflow" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:226 +msgid "Linters, code formatters and your favorite coding tools" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:228 +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:234 +msgid "Use pre-commit hooks to run code formatters and linters on commits" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:236 +msgid "You can also setup a `pre-commit hook` in your Python package repository." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:238 +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:241 +msgid "Pre-commit hook example workflow" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:243 +msgid "The precommit workflow looks like this: You type and run:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:246 +msgid "`git commit -m \"message here\"` at the command line" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:248 +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:250 +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:254 +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:261 +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:265 +msgid "Diagram showing the steps of a pre-commit workflow from left to right." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:267 +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:280 +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:287 +msgid "General pre commit checks" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:289 +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:294 +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:297 +msgid "Pre-commit.ci" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:299 +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:302 +msgid "It will check every pull request using all of the pre-commit hook setting" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:303 +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:306 +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:308 +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:311 +msgid "Setting up a bot like this can be valuable because:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:313 +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:315 +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:317 +msgid "Setting up a git pre-commit hook" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:319 +msgid "To setup pre-commit locally, you need to do 3 things:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:321 +msgid "" +"Install pre-commit (and include it as a development requirement in your " +"repository)" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:331 +msgid "" +"Create a .pre-commit-config.yaml file in the root of your package " +"directory." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:333 +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:341 +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:344 +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:346 +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:349 +msgid "Summary" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:351 +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 "" +"For comprehensive guidance on packaging compiled projects with " +"C/C++/Fortran/Rust extensions, see the [Scientific Python Development " +"Guide on compiled packaging](https://learn.scientific-" +"python.org/development/guides/packaging-compiled/). This is the best " +"reference for complex builds and covers scikit-build-core, meson-python, " +"maturin, and other modern build backends." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:8 +msgid "" +"If you have questions about these types of package, please 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:10 +msgid "Pure Python packages vs. packages with extensions in other languages" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:12 +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:16 +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:18 +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:20 +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:23 +msgid "Mixing frontend and backend projects" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:25 +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:31 +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:39 +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:6 +msgid "Dependencies for your Python Package" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:8 +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:14 +msgid "What is a package dependency?" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:16 +msgid "" +"A Python package dependency refers to an external package or A tool that " +"is needed when using or working on your Python project. Declare your " +"dependencies in your `pyproject.toml` file. This keeps all package " +"metadata in one place, making it simpler for users and contributors to " +"understand your package." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:19 +msgid "Older ways to declare dependencies" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:22 +msgid "" +"While `pyproject.toml` is now the standard, you may sometimes encounter " +"older approaches to storing dependencies \"in the wild\":" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:24 +msgid "" +"**requirements.txt**: Previously common for dependencies, still used by " +"some projects for local development" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:25 +msgid "" +"**setup.py or setup.cfg**: May be needed for packages with extensions in " +"other languages" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:27 +msgid "" +"[Learn more in the setuptools " +"documentation](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html" +"#declaring-required-dependency)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:30 +msgid "Why specify dependencies" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:32 +msgid "" +"Specifying dependencies in the [project.dependency] array of your " +"`pyproject.toml` file ensures that libraries needed to run your package " +"are correctly installed into a user's environment. For instance, if your " +"package requires Pandas to run properly, and you add Pandas to the " +"`project.dependency` array, Pandas will be installed into the users' " +"environment when they install your package using uv, pip, or conda." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:45 +msgid "" +"Development dependencies make it easier for contributors to work on your " +"package. You can set up instructions for running specific workflows, such" +" as tests, linting, and even typing, that automatically install groups of" +" development dependencies. These dependencies can be stored in arrays " +"(lists of dependencies) within a `[development-group]` table." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:55 +msgid "Types of dependencies" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:57 +msgid "" +"There are three different types of dependencies that you will learn about" +" on this page:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:59 +msgid "" +"**Required dependencies:** These are dependencies that need to be " +"installed for your package to work correctly in a user's environment. You" +" add these dependencies to the `[project.dependencies]` table in your " +"pyproject.toml file." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:60 +msgid "" +"**Feature Dependencies:** These are dependencies that are required if a " +"user wants to access additional functionality (that is not core) to your " +"package. Store these in the `[project.optional.dependencies]` table or " +"your pyproject.toml file." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:61 +msgid "" +"**Development Dependencies:** These dependencies are required if someone " +"wants to develop or work on your package. These include instance linters," +" testing tools like pytest and mypy are examples of development " +"dependencies. Store these in the `[project.dependency.groups]` table or " +"your pyproject.toml file." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:64 +msgid "" +"A dependency is not part of your project's codebase. It is a package or " +"software called within the code of your project or used during the " +"development of your package." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:69 +msgid "1. Required dependencies" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:71 +msgid "" +"Required dependencies are imported and called directly within your " +"package's code. They are needed for your package to run." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:74 +msgid "" +"You can add your required dependencies to the `dependencies` array in the" +" `[project]` table of your **pyproject.toml** file. When users install " +"your package with uv, pip, or conda, these dependencies will be " +"automatically installed alongside your package in their environment." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:92 +msgid "" +"Try your best to minimize dependencies whenever possible. Remember that " +"fewer dependencies reduce the possibility of version conflicts in user " +"environments." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md +msgid "How to Add Required Dependencies with UV" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:102 +#: ../../package-structure-code/declare-dependencies.md:162 +#: ../../package-structure-code/declare-dependencies.md:223 +msgid "You can use uv to add dependencies to your pyproject.toml file:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:104 +msgid "**Add a required dependency:**" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:110 +msgid "Will add numpy as a dependency to your `project.dependency` array:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:121 +msgid "Requiring packages from GitHub / Gitlab" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:124 +msgid "" +"If you have dependencies that need to be installed directly from GitHub, " +"you can specify them in your pyproject.toml file like this:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:133 +msgid "" +"IMPORTANT: If your library depends on a GitHub-hosted project, you should" +" point to a specific commit/tag/hash of that repository before you upload" +" your project to PyPI. You never know how the project might change over " +"time. Commit hashes are more reliable as they can't be changed" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:140 +msgid "2. Optional dependencies" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:142 +msgid "" +"Optional (also referred to as feature) dependencies can be installed by " +"users as needed. Optional dependencies add specific features to your " +"package that not all users need. For example, if your package has an " +"optional interactive plotting feature that uses Bokeh, you would list " +"Bokeh as an `[optional.dependency]`. Users who want interactive plotting " +"will install it. Users who don't need plotting don't have to install it." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:144 +msgid "Place these dependencies in the `[project.optional-dependencies]` table." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:155 +msgid "" +"When a user installs your package, uv, pip, or conda automatically " +"installs all required dependencies. Optional dependencies are only " +"installed if the user explicitly requests them." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md +msgid "How to Add optional.dependencies using UV" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:164 +msgid "**Add an optional dependency:**" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:170 +msgid "Will add this to your pyproject.toml file:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:181 +msgid "3. Dependency groups" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:183 +msgid "" +"Development dependencies include packages needed to work on your package " +"locally. They are used to perform tasks such as:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:186 +msgid "running your test suite (pytest, pytest-cov)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:187 +msgid "building your documentation (sphinx, sphinx-theme packages)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:188 +msgid "linting and formatting code (ruff, black)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:189 +msgid "building package distribution files (build, twine)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:191 +msgid "" +"Dependency groups are optional because they are not required for users to" +" install and use your package. However, they will make it easier for " +"contributors to your project to setup development environments locally." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:196 +msgid "New: PEP 735 development dependency groups" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:199 +msgid "" +"`[development-groups]` is a newer specification introduced by PEP 735. " +"They are intended to organize development dependencies and are " +"intentionally separate from `[project.optional-dependencies]`, which can" +" be installed into a user's environment." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:204 +msgid "How to declare dependency groups" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:206 +msgid "" +"You declare development dependencies in your **pyproject.toml** file " +"within a `[development-groups]` table." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:209 +msgid "" +"Similar to optional-dependencies, you can create separate subgroups or " +"arrays with names using the syntax: `group-name = [\"dep1\", \"dep2\"]`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md +msgid "How to Add [development.group] using UV" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:225 +msgid "**Add a development group dependency:**" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:232 +msgid "Will add the following to your pyproject.toml file:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:245 +#: ../../package-structure-code/declare-dependencies.md:251 +#: ../../package-structure-code/declare-dependencies.md:295 +#: ../../package-structure-code/declare-dependencies.md:414 +#: ../../package-structure-code/declare-dependencies.md:496 +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:14 +msgid "Todo" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:246 +msgid "" +"i'll pick back up here tomorrow - this section is all about how things " +"install and what \"ships\" with your package vs what just gets installed " +"via commands (ie development)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:249 +msgid "Understanding required vs. optional dependencies" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:252 +msgid "" +"The purpose of this section is to help users understand how dependencies " +"relate to what is installed in their environment. We have two graphics on" +" this page - one that breaks out the two buckets of tools (required and " +"optional) that both get installed into a user's envt vs development " +"groups, which are contributor/ development facing, not user-facing. When " +"we originally wrote this section, development groups didn't exist, and we" +" were using optional dependencies for dev groups." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:254 +msgid "" +"The graphic below is two circles representing optional vs regular / " +"required deps - created before development groups existed... there is " +"another graphi that shows what gets installed into a uses envt." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:258 +msgid "" +"Diagram showing two main groups of Python package dependencies: required " +"and optional. Required dependencies include core packages needed to use " +"your package. Optional dependencies include development dependencies for " +"working on the package locally and feature dependencies for additional " +"functionality." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:260 +msgid "" +"Python package dependencies fall into two categories: **required** " +"dependencies that users need to run your package, and **optional** " +"dependencies for development work or additional features." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:265 +msgid "Additional dependency resources" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:267 +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:268 +msgid "" +"[Dependency " +"specifiers](https://packaging.python.org/en/latest/specifications" +"/dependency-specifiers/)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:272 +msgid "Install dependency groups" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:274 +msgid "" +"When someone installs your package, only core dependencies are installed " +"by default. To install optional dependencies, you need to specify which " +"groups to include when installing the package." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:280 +msgid "" +"Diagram showing a Venn diagram with three sections representing " +"dependency groups - docs, feature, and tests. In the center it shows " +"your-package with core dependencies seaborn and numpy. Two arrows on the " +"right demonstrate: first, python -m pip install your-package installs " +"only the package and core dependencies. Second, python -m pip install " +"your-package[tests] installs the package, core dependencies, and test " +"dependencies including pytest and pytest-cov." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:282 +msgid "" +"When a user installs your package using `pip install your-package`, only " +"your package and its core dependencies get installed. When they install " +"with `pip install your-package[tests]`, pip will install your package, " +"core dependencies, and the test dependencies from the `[project.optional-" +"dependencies]` table." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:289 +msgid "Using uv or pip for installation" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:291 +msgid "" +"UV streamlines this process, allowing you to sync a venv in your project " +"directory with both an editable install of your package and its " +"dependencies automatically. You can also use pip and install dependencies" +" into the environment of your choice." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:296 +msgid "" +"We shouldn't show UV pip install, so how do you add optional feature deps" +" with UV??" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:299 +msgid "**Install development groups:**" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md +msgid "Use UV" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:305 +msgid "You can use uv sync to sync dependency groups in your uv-managed venv" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:313 +#: ../../package-structure-code/declare-dependencies.md:334 +msgid "**Install optional dependencies:**" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:321 +msgid "**Install everything (package + all dependencies):**" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:327 +msgid "" +"`uv sync` is the recommended command for development workflows. It " +"manages your virtual environment and keeps your lockfile up to date. Use " +"`uv pip install` when you need pip-compatible behavior." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md +msgid "Use pip (version >=25.1)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:341 +msgid "**Install dependency groups:**" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:348 +msgid "" +"Always call pip using `python -m pip` to ensure you're using the pip from" +" your current active Python environment. This helps avoid installation " +"conflicts." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:352 +msgid "" +"**Note:** Some shells (like zsh on Mac) require quotes around brackets to" +" run successfully:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:354 +msgid "`python -m pip install \".[tests]\"`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:360 +msgid "Combining dependency groups" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:362 +msgid "You can also create combined groups that reference other groups:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:371 +msgid "Then install everything with pip install or uv sync as needed:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:380 +msgid "" +"When you install optional dependencies, pip and uv install your package " +"and its core dependencies automatically." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:384 +msgid "Version specifiers for dependencies" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:386 +msgid "" +"Version specifiers control which versions of a dependency work with your " +"package. Use them to specify minimum versions, exclude buggy releases, or" +" set version ranges." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:390 +msgid "Common operators" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:392 +msgid "" +"**`>=`** Minimum version set: `numpy>=1.20` (This is the most common " +"approach and is recommended)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:393 +msgid "" +"**`==`** Exact version: `requests==2.28.0` (Avoid pinning dependencies " +"like this unless necessary)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:394 +msgid "" +"**`~=`** Compatible release: `django~=4.2.0` (Allows patches: " +">=4.2.0,<4.3.0)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:395 +msgid "**`<` or `>`** - Upper/lower bounds: `pandas>=1.0,<3.0`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:396 +msgid "" +"**`!=`** Exclude version: `scipy>=1.7,!=1.8.0` (Rare but allows you to " +"skip a buggy release version)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:399 +msgid "" +"**Best practice:** Use `>=` to specify your minimum tested version and " +"avoid upper bounds unless you know at what version that dependency is no " +"longer compatible. UV will do this by default when it adds a dependency " +"to your pyproject.toml file. This keeps your package flexible and reduces" +" dependency conflicts." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:415 +msgid "Using conda and Pixi" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:419 +msgid "" +"The `pyproject.toml` file works great for pure-Python packages. However, " +"some packages (particularly in the scientific Python ecosystem) require " +"dependencies written in other languages like C or Fortran. Conda was " +"created to support the distribution of tools with non-Python " +"dependencies." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:424 +msgid "**For conda users:**" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:426 +msgid "" +"You can maintain an `environment.yml` file to help users and contributors" +" set up conda environments. This is especially useful for packages with " +"system-level dependencies like GDAL." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:430 +msgid "**Consider Pixi for conda package focused workflows:**" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:432 +msgid "" +"[Pixi](https://pixi.sh) is a modern package manager built on top of both " +"the conda and Python package ecosystems. Pixi is able to treat conda and " +"Python package requirements with parity when resolving environments, but " +"uses a \"conda-first\" approach of using already resolved conda packages " +"if possible when resolving Python dependencies. Pixi [can also use " +"`pyproject.toml` for " +"configuration](https://pixi.sh/latest/python/pyproject_toml/). If your " +"project relies heavily on conda packages, Pixi offers a streamlined " +"workflow with faster dependency resolution and automatic lock file " +"support for full environment reproducibility. If you already have an " +"existing conda environment definition file, like an `environment.yml`, " +"you can [import the " +"environment](https://pixi.sh/latest/tutorials/import/) into a new Pixi " +"workspace with" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:450 +msgid "A note for conda users" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:453 +msgid "" +"If you use a conda environment for development and install your package " +"with `python -m pip install -e .` dependencies will be installed from " +"PyPI, potentially overwriting conda packages that had already been " +"installed. This can cause conflicts, especially for packages with system " +"dependencies." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:458 +msgid "To avoid this, install your package without dependencies:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:464 +msgid "Then install dependencies through your conda `environment.yml` file." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:467 +msgid "Dependencies in Read the Docs" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:469 +msgid "" +"Once you've specified dependencies in your `pyproject.toml`, you can use " +"them in other workflows like building documentation on Read the Docs." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:472 +msgid "" +"[Read the Docs](https://readthedocs.org) is a documentation platform that" +" automatically builds and publishes your documentation. To install your " +"dependencies during the build process, configure them in a " +"**readthedocs.yaml** file." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:477 +msgid "Here's an example that installs your `docs` optional dependencies:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:488 +msgid "Learn more about Read the Docs" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:491 +msgid "" +"[Creating a readthedocs.yaml file](https://docs.readthedocs.io/en/stable" +"/config-file/index.html)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:492 +msgid "" +"[Using uv with Read the Docs](https://docs.readthedocs.io/en/stable" +"/build-customization.html)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:493 +msgid "" +"[Using Poetry with Read the Docs](https://docs.readthedocs.io/en/stable" +"/build-customization.html#install-dependencies-with-poetry)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:498 +msgid "" +"Keep this comment - 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." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:500 +msgid "" +"Following this comment: " +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:503 +msgid "Jonny will add a section that talks about:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:505 +msgid "" +"Why you specify dependencies How to specify dependencies When you use " +"different specifiers" +msgstr "" + +#: ../../package-structure-code/intro.md:163 +msgid "Intro" +msgstr "" + +#: ../../package-structure-code/intro.md:163 +msgid "Python package structure" +msgstr "" + +#: ../../package-structure-code/intro.md:163 +msgid "pyproject.toml Package Metadata" +msgstr "" + +#: ../../package-structure-code/intro.md:163 +msgid "Declare dependencies" +msgstr "" + +#: ../../package-structure-code/intro.md:163 +msgid "Package Build Tools" +msgstr "" + +#: ../../package-structure-code/intro.md:163 +msgid "Build Your Package" +msgstr "" + +#: ../../package-structure-code/intro.md:163 +msgid "Complex Builds" +msgstr "" + +#: ../../package-structure-code/intro.md:163 +msgid "Create & Build Your Package" +msgstr "" + +#: ../../package-structure-code/intro.md:177 +msgid "Publish with Conda / PyPI" +msgstr "" + +#: ../../package-structure-code/intro.md:177 +msgid "Package versions" +msgstr "" + +#: ../../package-structure-code/intro.md:177 +msgid "Code style" +msgstr "" + +#: ../../package-structure-code/intro.md:177 +msgid "Publish your package" +msgstr "" + +#: ../../package-structure-code/intro.md:1 +msgid "Python Package Structure & Code" +msgstr "" + +#: ../../package-structure-code/intro.md:3 +msgid "" +"This section covers everything you need to structure your Python package," +" configure metadata, choose build tools, and publish your package to PyPI" +" and conda-forge." +msgstr "" + +#: ../../package-structure-code/intro.md:9 +msgid "New to Python packaging?" +msgstr "" + +#: ../../package-structure-code/intro.md:13 +msgid "**Start with our step-by-step tutorials:**" +msgstr "" + +#: ../../package-structure-code/intro.md:15 +msgid "Follow along as we create a package from scratch" +msgstr "" + +#: ../../package-structure-code/intro.md:16 +msgid "Learn by doing with guided examples" +msgstr "" + +#: ../../package-structure-code/intro.md:17 +msgid "Perfect for your first package" +msgstr "" + +#: ../../package-structure-code/intro.md:19 +msgid "Start the tutorial series" +msgstr "" + +#: ../../package-structure-code/intro.md:27 +msgid "Already have code to package?" +msgstr "" + +#: ../../package-structure-code/intro.md:30 +msgid "**Jump into the reference guides:**" +msgstr "" + +#: ../../package-structure-code/intro.md:32 +msgid "Learn about package structure and metadata" +msgstr "" + +#: ../../package-structure-code/intro.md:33 +msgid "Compare build tools and choose what's right for you" +msgstr "" + +#: ../../package-structure-code/intro.md:34 +msgid "Understand the publishing process" +msgstr "" + +#: ../../package-structure-code/intro.md:36 +msgid "Start with the cards below ↓" +msgstr "" + +#: ../../package-structure-code/intro.md:40 +msgid "How this content is developed" +msgstr "" + +#: ../../package-structure-code/intro.md:43 +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:46 +msgid "What you'll learn" +msgstr "" + +#: ../../package-structure-code/intro.md:48 +msgid "In this section, you'll learn how to:" +msgstr "" + +#: ../../package-structure-code/intro.md:50 +msgid "" +"**Structure your package** - Choose between src and flat layouts, " +"organize tests and documentation" +msgstr "" + +#: ../../package-structure-code/intro.md:51 +msgid "" +"**Configure metadata** - Set up `pyproject.toml` with project " +"information, dependencies, and versioning" +msgstr "" + +#: ../../package-structure-code/intro.md:52 +msgid "" +"**Choose build tools** - Compare Hatch, PDM, Poetry, and setuptools to " +"find the right fit" +msgstr "" + +#: ../../package-structure-code/intro.md:53 +msgid "" +"**Build distributions** - Create sdist and wheel files ready for " +"publication" +msgstr "" + +#: ../../package-structure-code/intro.md:54 +msgid "" +"**Publish your package** - Make your package available on PyPI and " +"optionally conda-forge" +msgstr "" + +#: ../../package-structure-code/intro.md:55 +msgid "" +"**Maintain code quality** - Set up linters and formatters to keep your " +"code consistent" +msgstr "" + +#: ../../package-structure-code/intro.md:57 +msgid "" +"Our recommendations align with current [Python packaging " +"standards](https://packaging.python.org/en/latest/) and [Scientific " +"Python community specs](https://scientific-python.org/specs/), while " +"prioritizing tools that are beginner-friendly and well-maintained." +msgstr "" + +#: ../../package-structure-code/intro.md:59 +msgid "Package setup" +msgstr "" + +#: ../../package-structure-code/intro.md:66 +msgid "✨ Package file structure ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:68 +msgid "" +"Learn how to organize your package files using [src or flat layouts" +"](package-source-layout). This page helps you decide on a package " +"structure that follows modern Python best practices, including where to " +"place [tests](src-layout-test) and [documentation](package-source-" +"layout)." +msgstr "" + +#: ../../package-structure-code/intro.md:71 +msgid "✨ Add metadata ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:73 +msgid "" +"Learn how to add [project metadata](pyproject-toml-python-package-" +"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:78 +msgid "✨ Declare dependencies ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:80 +msgid "" +"Learn how to specify [required dependencies](required-dependencies), " +"[optional feature dependencies](optional-dependencies), and [development " +"dependencies](dependency-groups) in your [pyproject.toml file](pyproject-" +"toml-overview)." +msgstr "" + +#: ../../package-structure-code/intro.md:83 +msgid "✨ Setup package versioning ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:85 +msgid "" +"Learn how to manage package versions using [semantic versioning (SemVer" +")](package-versioning) or [calendar versioning (CalVer)](package-" +"versioning). This page helps you choose the right versioning strategy and" +" set up [automated version management](tools-version-management) using " +"tools like hatch_vcs or setuptools-scm." +msgstr "" + +#: ../../package-structure-code/intro.md:89 +msgid "Development practices" +msgstr "" + +#: ../../package-structure-code/intro.md:96 +msgid "✨ Code style & linters ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:98 +msgid "" +"Learn how to set up [code formatters and linters](code-style-tools) " +"([Black](about-black), [Ruff](about-ruff), [flake8](about-flake8)) to " +"ensure your package follows [PEP 8 standards](code-style-tools) and " +"maintains consistent code style throughout your project." +msgstr "" + +#: ../../package-structure-code/intro.md:102 +msgid "Build & publish" +msgstr "" + +#: ../../package-structure-code/intro.md:109 +msgid "✨ Choose your build tool ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:111 +msgid "" +"Learn how to choose the right packaging tool for your project. Compare " +"[Hatch](about-hatch), [PDM](about-pdm), [Poetry](about-poetry), and " +"[setuptools](about-setuptools) to find the best fit for your workflow. " +"See the [summary comparison](summary-build-tools) to help decide." +msgstr "" + +#: ../../package-structure-code/intro.md:114 +msgid "✨ Build your package ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:116 +msgid "" +"Learn how to build your Python package into [distribution files](build-" +"package) ([sdist](python-source-distribution) and [wheel](python-wheel)) " +"that can be published on [PyPI](publish-pypi-conda)." +msgstr "" + +#: ../../package-structure-code/intro.md:119 +msgid "✨ Publish to PyPI and Conda ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:121 +msgid "" +"Learn how to publish your package to [PyPI](publish-pypi-conda) and " +"optionally to [conda-forge](how-to-submit-to-conda-forge). This page " +"covers the complete process for making your package available to users, " +"including the [conda-forge submission process](how-to-submit-to-conda-" +"forge) after publishing to PyPI." +msgstr "" + +#: ../../package-structure-code/intro.md:125 +msgid "Choosing the right tools" +msgstr "" + +#: ../../package-structure-code/intro.md:127 +msgid "" +"Not sure which build tool to use? This decision tree can help you choose " +"based on your package's needs:" +msgstr "" + +#: ../../package-structure-code/intro.md:131 +msgid "" +"Figure showing a decision tree with the various packaging tool front-end " +"and back-end options." +msgstr "" + +#: ../../package-structure-code/intro.md:133 +msgid "" +"Use this decision tree to help select a packaging tool. See the " +"[packaging tools page](python-package-build-tools) for detailed " +"comparisons and recommendations." +msgstr "" + +#: ../../package-structure-code/intro.md:136 +msgid "Our recommendations" +msgstr "" + +#: ../../package-structure-code/intro.md:138 +msgid "We suggest tools and approaches based on three principles:" +msgstr "" + +#: ../../package-structure-code/intro.md:140 +msgid "" +"**Beginner-friendly** - Tools that are easy to learn and use for those " +"new to packaging" +msgstr "" + +#: ../../package-structure-code/intro.md:141 +msgid "**Well-maintained** - Tools with active development and good documentation" +msgstr "" + +#: ../../package-structure-code/intro.md:142 +msgid "" +"**Standards-aligned** - Tools that follow current [Python packaging " +"standards](https://packaging.python.org/en/latest/) and [Scientific " +"Python community specs](https://scientific-python.org/specs/)" +msgstr "" + +#: ../../package-structure-code/intro.md:144 +msgid "Pure Python vs. complex builds" +msgstr "" + +#: ../../package-structure-code/intro.md:146 +msgid "" +"**Pure Python packages** can use any modern tool (Hatch, PDM, Poetry, " +"Flit) - choose based on the features you want" +msgstr "" + +#: ../../package-structure-code/intro.md:147 +msgid "" +"**Packages with C/C++ extensions** may need additional build steps. See " +"our [complex builds page](complex-python-package-builds) for guidance. " +"For comprehensive information on packaging compiled projects, see the " +"[Scientific Python Development Guide on compiled packaging](https://learn" +".scientific-python.org/development/guides/packaging-compiled/)." +msgstr "" + +#: ../../package-structure-code/intro.md:149 +msgid "" +"Most scientific Python packages start simple and can evolve to handle " +"more complex requirements as needed." +msgstr "" + +#: ../../package-structure-code/intro.md:151 +msgid "Submitting your package for peer review?" +msgstr "" + +#: ../../package-structure-code/intro.md:153 +msgid "" +"If you're planning to submit your package to pyOpenSci for [peer " +"review](https://www.pyopensci.org/about-peer-review/index.html), check " +"out our [editor checklist](https://www.pyopensci.org/software-peer-review" +"/how-to/editor-in-chief-guide.html#editor-checklist-template) for the " +"minimum requirements. These checks are useful for anyone creating a " +"Python package, not just those submitting for review." +msgstr "" + +#: ../../package-structure-code/intro.md:155 +msgid "These are recommendations, not requirements" +msgstr "" + +#: ../../package-structure-code/intro.md:158 +msgid "" +"The suggestions in this guide are designed to help you create a well-" +"structured package. They are **not** specific requirements for pyOpenSci " +"peer review." +msgstr "" + +#: ../../package-structure-code/intro.md:160 +msgid "" +"If you're submitting to pyOpenSci, see our [package " +"scope](https://www.pyopensci.org/software-peer-review/about/package-" +"scope.html) and [author guide](https://www.pyopensci.org/software-peer-" +"review/how-to/author-guide.html#) for actual 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:23 +#: ../../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:25 +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:51 +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:59 +msgid "What is conda and Anaconda.org?" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:61 +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:65 +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:68 +msgid "A brief history of conda's evolution" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:71 +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:75 +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:77 +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:81 +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:89 +msgid "conda channels" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:91 +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:94 +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:97 +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:98 +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:99 +msgid "" +"[**bioconda**](https://bioconda.github.io/): this channel focuses on " +"biomedical tools." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:101 +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:106 +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:108 +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:111 +msgid "conda channels, PyPI, conda, pip - Where to publish your package" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:113 +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:116 +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:119 +msgid "The answer to both questions relates dependency conflicts." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:123 +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:125 +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:133 +msgid "Managing Python package dependency conflicts" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:135 +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:142 +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:144 +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:148 +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:150 +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:155 +msgid "Additional resources" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:157 +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:159 +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:174 +msgid "Click here for a tutorial on adding your package to conda-forge." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:181 +msgid "If you want a step by step tutorial, click here." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:183 +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:186 +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:189 +msgid "Maintaining your conda-forge package repository" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:191 +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:197 +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:2 +msgid "Use a pyproject.toml file for your package configuration & metadata" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:4 +msgid "pyproject.toml takeaways" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:6 +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:7 +msgid "" +"There are two _required_ fields in the **[project]** table: **name=** and" +" **version=**." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:8 +msgid "" +"Add metadata to the classifiers section of your `pyproject.toml` file to " +"make it easier for users to find your project on PyPI." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:9 +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:10 +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:16 +msgid "when these are published, remove this todo" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:25 +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:39 +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:50 +msgid "About the pyproject.toml file" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:52 +msgid "" +"Every modern Python package should include a `pyproject.toml` file. For " +"pure Python packages, this file replaces the `setup.py` and/or " +"`setup.cfg` file to describe project metadata." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:54 +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:56 +msgid "Tutorial" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:59 +msgid "" +"If you are migrating from a **setup.py** or **setup.cfg** file, and want " +"help, [check out this tutorial.](migrate-pyproj) [specify build " +"requirements and metadata is called a " +"**pyproject.toml**](https://packaging.python.org/en/latest/specifications" +"/declaring-project-metadata/)" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:64 +msgid "About the .toml format" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:66 +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" +" based 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:70 +msgid "Below `[build-system]` is considered a table in the toml language." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:71 +msgid "Within the `build-system` table, `requires =` is a key." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:72 +msgid "" +"The associated value for `requires` is an array containing the value " +"`\"hatchling\"`." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:80 +msgid "How the pyproject.toml is used when you build a package" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:84 +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:86 +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:82 +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:91 +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:87 +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:96 +msgid "Benefits of using a pyproject.toml file" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:98 +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:101 +msgid "Setup.py is still useful for complex package builds" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:105 +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:111 +msgid "Optional vs. required pyproject.toml file fields" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:113 +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:115 +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:117 +msgid "Required fields for the `[project]` table" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:119 +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:121 +msgid "`name`: This is the name of your project provided as a string" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:122 +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:124 +msgid "Optional fields to include in the `[project]` table" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:126 +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:131 +msgid "**Description:** this is a short one-line description of your package." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:132 +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:133 +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:134 +msgid "**License:** the license you are using" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:135 +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:136 +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:144 +msgid "" +"**project.dependencies:** The dependency group is optional because not " +"all packages require dependencies. However, if your project has specific " +"dependencies, include this section in your `pyproject.toml`. Dependencies" +" declared in the pyproject.toml file will be installed by uv or pip when " +"your project is installed." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:146 +msgid "" +"**project.optional-dependencies:** Optional or feature dependencies will " +"be installed if someone runs `python -m pip install " +"projectname[feature]`. Use this array to declare dependencies that add " +"specific features to your package that are not installed by default when " +"a user runs `uv sync` or `python -m pip install packagename`." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:147 +msgid "" +"**dependency-groups:** Dependency groups organize packages and tools that" +" a contributor or developer would need to work on your package. These " +"dependencies may include tools for building and running tests, linters, " +"and code formatters. This is an optional but highly suggested way to " +"organize and install dependencies. This section can replace a " +"requirements.txt file. [Learn more about adding these to your package in " +"the PyPA guide " +"here.](https://packaging.python.org/en/latest/specifications/dependency-" +"groups/)" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:148 +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:149 +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 " +"here](https://PyPI.org/classifiers/). Some of the classifiers that you " +"should consider including" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:150 +msgid "Development Status" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:151 +msgid "Intended Audience" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:152 +msgid "Topic" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:153 +msgid "Programming language" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:155 +msgid "Advanced options in the pyproject.toml file" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:157 +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:159 +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:160 +msgid "" +"Use **Dynamic Fields** If you have fields that are dynamically populated." +" For example, you may wish to automatically update your package's version" +" using Git tags (SCM/version control-based versioning). Example: " +"**dynamic = [\"version\"]**" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:162 +#: ../../package-structure-code/python-package-build-tools.md:398 +msgid "Add dependencies to your pyproject.toml file" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:164 +msgid "" +"The `pyproject.toml` file is a modern replacement for the " +"`requirements.txt` file, which has been traditionally used to store " +"development dependencies and also configuration for tools such as pytest," +" black, and others." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:166 +msgid "" +"To add development dependencies to your build, add a `[dependency-" +"groups]` array to your pyproject.toml file." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:168 +msgid "Then specify dependency groups as follows:" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:176 +msgid "Following the above example, you install dependencies like this:" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:178 +msgid "`python -m pip install -e .[tests]`" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:180 +msgid "pip install --group test _# requires pip 25.1 or greater_" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:182 +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:184 +msgid "To install all dependencies and also your package, you'd use:" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:186 +msgid "`python -m pip install -e .[tests,lint,docs]`" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:188 +msgid "Recursive dependencies" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:192 +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:195 +msgid "Example pyproject.toml for building using hatchling" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:197 +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:205 +msgid "Notice that dependencies are specified in this file." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:207 +msgid "Example pyproject.toml for building using setuptools" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:209 +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:213 +msgid "In this example package setup you use:" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:215 +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:216 +msgid "" +"**setuptools_scm** to manage package version updates using version " +"control tags" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:218 +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:221 +msgid "`requires =`" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:222 +msgid "`build-back-end =`" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:229 +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:4 +msgid "Tools for building your package" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:6 +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:14 +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:16 +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:19 +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:22 +msgid "Tools that we review here" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:24 +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:28 +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:29 +msgid "[Flit](https://flit.pypa.io/en/stable/)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:30 +msgid "[Hatch](https://hatch.pypa.io/latest/)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:31 +msgid "[PDM](https://pdm-project.org/latest/)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:32 +msgid "[Poetry](https://python-poetry.org/docs/)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:35 +msgid "Summary of tools Hatch vs. PDM vs. Poetry (and setuptools)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:37 +msgid "If you are looking for a quick summary, read below." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:39 +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:40 +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:41 +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:43 +msgid "Below are some features that Hatch and PDM offer that Poetry does not." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:45 +msgid "PDM:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:47 +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:48 +msgid "Offers flexibility in dependency management which we like" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:49 +msgid "Offers lock files if you need them" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:51 +msgid "Hatch:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:53 +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:54 +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:57 +msgid "Build front-end vs. build back-end tools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:59 +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:64 +msgid "Build back-ends" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:66 +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:73 +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:79 +msgid "Python package build front-ends" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:81 +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:84 +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:85 +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:86 +msgid "Publishing to PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:87 +msgid "Running tests" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:88 +msgid "Building documentation" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:89 +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:91 +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:95 +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:102 +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:105 +msgid "Example build steps that can be simplified using a front-end tool" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:107 +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:117 +msgid "Example build steps using the **setuptools** back-end and **build**:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:127 +msgid "Choosing a build back-end" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:129 +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:134 +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:135 +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:137 +msgid "Build back-end support for non pure-python packages" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:139 +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:142 +msgid "setuptools supports builds using C / C++ extensions" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:143 +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:144 +msgid "PDM's back-end supports C / C++ extensions by using setuptools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:145 +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:147 +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:150 +msgid "An ecosystem of Python build tools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:152 +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:156 +msgid "We do not suggest using setuptools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:159 +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:163 +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:167 +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:173 +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:175 +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:178 +msgid "Chose a build workflow tool" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:180 +msgid "The tools that we review below include:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:182 +msgid "Twine, Build + setuptools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:183 +#: ../../package-structure-code/python-package-build-tools.md:217 +#: ../../package-structure-code/python-package-build-tools.md:294 +#: ../../package-structure-code/python-package-build-tools.md:307 +msgid "Flit" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:184 +#: ../../package-structure-code/python-package-build-tools.md:217 +#: ../../package-structure-code/python-package-build-tools.md:336 +#: ../../package-structure-code/python-package-build-tools.md:353 +msgid "Hatch" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:185 +#: ../../package-structure-code/python-package-build-tools.md:217 +#: ../../package-structure-code/python-package-build-tools.md:233 +#: ../../package-structure-code/python-package-build-tools.md:254 +msgid "PDM" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:186 +#: ../../package-structure-code/python-package-build-tools.md:217 +#: ../../package-structure-code/python-package-build-tools.md:380 +#: ../../package-structure-code/python-package-build-tools.md:398 +msgid "Poetry" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:188 +msgid "" +"When you are selecting a tool, you might consider this general workflow " +"of questions:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:191 +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:193 +msgid "Flit, Hatch, PDM or Poetry (read below for more)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:195 +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:199 +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:201 +msgid "Python packaging tools summary" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:203 +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:206 +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:210 +msgid "Package tool features table" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:217 +#: ../../package-structure-code/python-package-build-tools.md:254 +#: ../../package-structure-code/python-package-build-tools.md:307 +#: ../../package-structure-code/python-package-build-tools.md:353 +#: ../../package-structure-code/python-package-build-tools.md:398 +msgid "Feature" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:217 +msgid "Default Build Back-end" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:217 +msgid "Flit-core" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:217 +msgid "hatchling" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:217 +msgid "Poetry-core" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:217 +#: ../../package-structure-code/python-package-build-tools.md:254 +#: ../../package-structure-code/python-package-build-tools.md:353 +msgid "Use Other Build Backends" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:217 +#: ../../package-structure-code/python-package-build-tools.md:353 +msgid "✖" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:217 +#: ../../package-structure-code/python-package-build-tools.md:254 +#: ../../package-structure-code/python-package-build-tools.md:307 +#: ../../package-structure-code/python-package-build-tools.md:353 +#: ../../package-structure-code/python-package-build-tools.md:398 +msgid "✅" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:217 +#: ../../package-structure-code/python-package-build-tools.md:353 +msgid "Dependency management" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:217 +#: ../../package-structure-code/python-package-build-tools.md:254 +msgid "Publish to PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:217 +msgid "Version Control based versioning (using `git tags`)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:217 +#: ../../package-structure-code/python-package-build-tools.md:254 +#: ../../package-structure-code/python-package-build-tools.md:353 +#: ../../package-structure-code/python-package-build-tools.md:398 +msgid "Version bumping" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:217 +#: ../../package-structure-code/python-package-build-tools.md:353 +msgid "Environment Management" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:217 +msgid "More than one maintainer? (bus factor)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:227 +msgid "Notes:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:229 +msgid "_Hatch plans to support dependency management in the future_" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:230 +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:235 +msgid "" +"[PDM is a Python packaging and dependency management tool](https://pdm-" +"project.org/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:239 +msgid "PDM support for C and C++ extensions" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:241 +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:247 +msgid "PDM features" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:254 +#: ../../package-structure-code/python-package-build-tools.md:307 +#: ../../package-structure-code/python-package-build-tools.md:353 +#: ../../package-structure-code/python-package-build-tools.md:398 +msgid "Notes" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:254 +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:254 +msgid "Dependency specifications" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:254 +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-project.org/en/latest/usage/dependency/#about-update-" +"strategy).**" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:254 +msgid "Environment lock files" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:254 +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:254 +#: ../../package-structure-code/python-package-build-tools.md:398 +msgid "Environment management" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:254 +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:254 +msgid "Select your environment type on install" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:254 +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:254 +msgid "PDM supports publishing to both test PyPI and PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:254 +#: ../../package-structure-code/python-package-build-tools.md:353 +#: ../../package-structure-code/python-package-build-tools.md:398 +msgid "Version Control based versioning" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:254 +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:254 +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:254 +#: ../../package-structure-code/python-package-build-tools.md:307 +#: ../../package-structure-code/python-package-build-tools.md:353 +#: ../../package-structure-code/python-package-build-tools.md:398 +msgid "Follows current packaging standards" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:254 +msgid "" +"PDM supports current packaging standards for adding metadata to the " +"**pyproject.toml** file." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:254 +#: ../../package-structure-code/python-package-build-tools.md:307 +#: ../../package-structure-code/python-package-build-tools.md:353 +#: ../../package-structure-code/python-package-build-tools.md:398 +msgid "Install your package in editable mode" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:254 +msgid "PDM supports installing your package in editable mode." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:254 +#: ../../package-structure-code/python-package-build-tools.md:307 +#: ../../package-structure-code/python-package-build-tools.md:353 +#: ../../package-structure-code/python-package-build-tools.md:398 +msgid "Build your sdist and wheel distributions" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:254 +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:267 +msgid "PDM vs. Poetry" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:268 +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:272 +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:274 +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:275 +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:277 +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:280 +msgid "Challenges with PDM" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:282 +msgid "" +"PDM is a full-featured packaging tool. However it is not without " +"challenges:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:284 +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:286 +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:291 +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:296 +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:300 +msgid "Flit features" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:307 +#: ../../package-structure-code/python-package-build-tools.md:353 +#: ../../package-structure-code/python-package-build-tools.md:398 +msgid "Publish to PyPI and test PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:307 +msgid "Flit supports publishing to both test PyPI and PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:307 +msgid "Helps you add metadata to your **pyproject.toml** file" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:307 +msgid "" +"Flit does support adding metadata to your **pyproject.toml** file " +"following modern packaging standards." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:307 +msgid "" +"Flit supports current packaging standards for adding metadata to the " +"**pyproject.toml** file." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:307 +msgid "Flit supports installing your package in editable mode.**" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:307 +msgid "Flit can be used to build your packages sdist and wheel distributions." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:314 +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:316 +msgid "Learn more about flit" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:318 +msgid "[Why use flit?](https://flit.pypa.io/en/stable/rationale.html)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:321 +msgid "Why you might not want to use Flit" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:323 +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:327 +msgid "You may NOT want to use flit if:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:329 +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:330 +msgid "" +"You want a tool that handles dependency versions (use PDM or Poetry " +"instead)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:331 +msgid "You have a project that is not pure Python (Use Hatch, PDM or setuptools)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:332 +msgid "You want environment management (use PDM, Hatch or Poetry)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:338 +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:345 +msgid "Hatch features" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:353 +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:353 +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:353 +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:353 +msgid "Hatch supports publishing to both test PyPI and PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:353 +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:353 +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:353 +msgid "" +"Hatch supports current packaging standards for adding metadata to the " +"**pyproject.toml** file." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:353 +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:353 +msgid "Hatch will build the sdist and wheel distributions" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:353 +msgid "✨Matrix environment creation to support testing across Python versions✨" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:353 +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:353 +msgid "" +"✨[Nox / MAKEFILE like " +"functionality](https://hatch.pypa.io/latest/environment/#selection)✨" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:353 +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:353 +msgid "✨A flexible build backend: **hatchling**✨" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:353 +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:367 +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:369 +msgid "Why you might not want to use Hatch" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:371 +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:374 +msgid "" +"Hatch doesn't support adding dependencies. You will have to add them " +"manually." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:375 +msgid "Hatch won't by default recognize Conda environments without a plugin." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:376 +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:377 +msgid "Hatch, similar to PDM and Flit currently only has one maintainer." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:382 +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:387 +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:391 +msgid "Poetry features" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:398 +msgid "Poetry helps you add dependencies to your `pyproject.toml` metadata." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:398 +msgid "Dependency specification" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:398 +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:398 +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:398 +msgid "Lock files" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:398 +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:398 +msgid "Poetry supports publishing to both test PyPI and PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:398 +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:398 +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:398 +msgid "" +"Since version 2.0, Poetry supports most current project metadata " +"standards. However, not all standards are supported, and it also supports" +" the legacy Poetry format. Read below for more." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:398 +msgid "Poetry supports installing your package in editable mode." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:398 +msgid "Poetry will build your sdist and wheel distributions using `poetry build`" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:413 +msgid "Challenges with Poetry" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:415 +msgid "Some challenges of Poetry include:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:417 +msgid "" +"Poetry has its own concept of grouped dependencies (`poetry add " +"--group=GROUP_NAME DEPENDENCY`). Dependencies added as grouped " +"dependencies are not optional and there is no Python standard for this " +"type of dependency. This should not be confused with \"optional\" " +"dependencies (`poetry add --optional=GROUP_NAME DEPENDENCY`), which is " +"standardised and lets you group your dependencies into several optional " +"groups." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:418 +msgid "" +"While Poetry supports \"development\" dependencies (i.e. dependencies you" +" use for development but not running the code, such as `pytest`), Poetry " +"does not yet follow the standardised format for specifying such " +"dependencies." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:419 +msgid "" +"Poetry, by default, pins dependencies using an \"upper bound\" limit " +"(which is specified with the `^` symbol in the legacy format). 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:421 +msgid "" +"Poetry is a popular packaging tool and introduced many very useful " +"features. However, if you decide to use it, then use caution when adding " +"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:426 +msgid "Challenges with Poetry dependency pinning" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:429 +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:435 +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:440 +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:445 +msgid "Using Setuptools back-end for Python packaging with Build front-end" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:447 +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:455 +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:458 +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:461 +msgid "Setuptools features" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:463 +msgid "Some of features of setuptools include:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:465 +msgid "Fully customizable build workflow" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:466 +msgid "Many scientific Python packages use it." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:467 +msgid "" +"It offers version control based package versioning using " +"**setuptools_scm**" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:468 +msgid "It supports modern packaging using **pyproject.toml** for metadata" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:469 +msgid "Supports backwards compatibly for older packaging approaches." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:471 +msgid "Challenges using setuptools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:475 +msgid "Setuptools has a few challenges:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:477 +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:478 +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:481 +msgid "" +"The above-mentioned backwards compatibility makes for a more complex " +"code-base." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:482 +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:484 +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:487 +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:489 +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 address different topics or that support " +"specific versions of python." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:72 +msgid "What happened to setup.py and setup.cfg for metadata?" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:75 +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:78 +msgid "An example - xclim" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:80 +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:93 +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:95 +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:100 +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:102 +msgid "PyPI screenshot showing metadata for the xclim package." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:109 +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:111 +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:114 +msgid "How to create the distribution format that PyPI and Pip expects?" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:116 +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:120 +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:126 +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:132 +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:135 +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:141 +msgid "Learn more about both distributions below." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:144 +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:149 +msgid "" +"Also note that we are not discussing conda build workflows in this " +"section. [You can learn more about conda builds " +"here.](https://docs.conda.io/projects/conda-build/en/latest/user-" +"guide/tutorials/index.html)" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:154 +msgid "What is a source distribution (sdist)" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:156 +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:160 +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:164 +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:166 +msgid "Below is an example sdist for the stravalib Python package:" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:218 +msgid "GitHub archive vs sdist" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:220 +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:228 +msgid "What is a Python wheel (whl):" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:230 +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:237 +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:239 +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:243 +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:251 +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:258 +msgid "The filename of a wheel contains important metadata about your package." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:260 +msgid "Example: **stravalib-1.1.0.post2-py3-none.whl**" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:262 +msgid "name: stravalib" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:263 +msgid "version: 1.1.0" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:264 +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:265 +msgid "py3: supports Python 3.x" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:266 +msgid "none: is not operating system specific (runs on windows, mac, linux)" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:267 +msgid "any: runs on any computer processor / architecture" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:269 +msgid "What a wheel file looks like when unpacked (unzipped):" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:303 +msgid "[Read more about the wheel format here](https://pythonwheels.com/)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:1 +msgid "Python Package Structure & Layout" +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:24 +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:27 +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:38 +msgid "What is the Python package source layout?" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:40 +msgid "An example of the **src/package** layout structure is below." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:62 +msgid "Note the location of the following directories in the example above:" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:64 +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:65 +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:66 +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:68 +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:72 +msgid "CHANGELOG.md" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:73 +msgid "CODE_OF_CONDUCT.md" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:74 +msgid "CONTRIBUTING.md" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:75 +msgid "LICENSE.txt" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:76 +msgid "README.md" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:80 +msgid "Click here to read about our packaging documentation requirements." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:87 +msgid "Example scientific packages that use **src/package** layout" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:89 +msgid "[Sourmash](https://github.com/sourmash-bio/sourmash)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:90 +msgid "[bokeh](https://github.com/bokeh/bokeh)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:91 +msgid "[openscm](https://github.com/openscm/openscm-runner)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:92 +msgid "[awkward](https://github.com/scikit-hep/awkward)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:93 +msgid "[poliastro](https://github.com/poliastro/poliastro/)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:98 +msgid "The src layout and testing" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:100 +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:106 +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:108 +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:110 +msgid "How Python discovers and prioritizes importing modules" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:112 +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:114 +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:116 +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:118 +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:121 +msgid "Don't include tests in your package wheel" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:123 +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:132 +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:134 +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:136 +msgid "Challenges with including tests and data in a package wheel" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:139 +msgid "" +"Tests, especially when accompanied by test data, can create a few small " +"challenges, including:" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:141 +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:142 +msgid "Large file sizes can also slow down package installation." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:144 +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:147 +msgid "**Don't include test suite datasets in your package**" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:149 +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:155 +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:157 +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:161 +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:167 +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:188 +msgid "Why most scientific Python packages do not use src/ layout" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:191 +msgid "" +"Migrating larger scientific packages that already use a flat layout would" +" consume significant time and resources." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:193 +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:196 +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:200 +msgid "What does the flat layout structure look like?" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:202 +msgid "The flat layout's primary characteristics are:" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:204 +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:206 +msgid "" +"Often the `tests/` directory also lives within that same `package` " +"directory." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:208 +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:230 +msgid "Benefits of using the flat layout in your Python package" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:232 +msgid "" +"There are some benefits to the scientific community in using the flat " +"layout." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:234 +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:236 +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:242 +msgid "Core scientific Python packages that use the flat layout" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:245 +msgid "[numpy](https://github.com/numpy/numpy)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:246 +msgid "[scipy](https://github.com/scipy/scipy)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:247 +msgid "[pandas](https://github.com/pandas-dev/pandas)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:248 +msgid "[xarray](https://github.com/pydata/xarray)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:249 +msgid "[Jupyter-core](https://github.com/jupyter/jupyter_core)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:250 +msgid "[Jupyter notebook](https://github.com/jupyter/notebook)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:251 +msgid "[scikit-learn](https://github.com/scikit-learn/scikit-learn)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:253 +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-structure.md:258 +msgid "Multiple packages in a src/ folder" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:261 +msgid "" +"In some more advanced cases, you may have more than one package in your " +"**src/** directory. See [Black's GitHub " +"repo](https://github.com/psf/black/tree/main/src) for an example of this." +" However, for most beginners you will likely only have one sub-directory " +"in your **src/** folder." +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:38 +msgid "SemVer rules" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:40 +msgid "Following SemVer, your bump your package version to a:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:42 +msgid "patch (1.1.1 --> 1.1.**2**)" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:43 +msgid "minor (1.1.1 --> 1.**2**.1)" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:44 +msgid "major (1.1.1 --> **2**.1.1)" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:46 +msgid "version number change based on the following rules:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:48 +msgid "Given a version number MAJOR.MINOR.PATCH, increment the:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:50 +msgid "**MAJOR version** when you make incompatible API changes" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:51 +msgid "" +"**MINOR version** when you add functionality in a backwards compatible " +"manner" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:52 +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:57 +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:60 +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:64 +msgid "Avoid manually updating Python package version numbers if you can" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:66 +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:71 +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:75 +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:79 +msgid "" +"Below we discuss some tools that you can use to manage updating Python " +"package versions." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:85 +msgid "Tools to manage versions for your Python package" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:87 +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:93 +msgid "Below, we provide an overview of these tools." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:99 +msgid "" +"There are three general groups of tools that you can use to manage " +"package versions:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:102 +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:104 +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:105 +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:107 +msgid "Semantic release, vs version control based vs manual version bumping" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:109 +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:115 +msgid "Builds your package and updates the version following the new tag" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:116 +msgid "Tests the build and publishes to test PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:117 +msgid "Publishes the package to PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:120 +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:124 +msgid "" +"Using semantic versioning, there are three main \"levels\" of versions " +"that you might consider:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:127 +msgid "Major, minor and patch. These are described in more detail below." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:130 +msgid "Tools for bumping Python package versions" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:132 +msgid "" +"In this section we discuss the following tools for managing your Python " +"package's version:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:135 +msgid "hatch &" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:136 +msgid "hatch_vcs plugin for hatchling" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:137 +msgid "setuptools-scm" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:138 +msgid "python-semantic-version" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:140 +msgid "Tool 1: Hatch and other build tools that offer incremental versioning" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:142 +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:148 +msgid "`tool-name version update major`" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:149 +msgid "`tool-name version update minor`" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:151 +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:154 +msgid "Hatch (or other tools like PDM) pros" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:156 +msgid "Easy to use version updates locally using a single tool!" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:158 +msgid "Hatch (or other tools like PDM) cons" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:160 +msgid "" +"There will be some setup involved to ensure package version is updated " +"throughout your package" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:162 +msgid "Tool 2: Hatch_vcs & hatchling build back-end" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:164 +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:169 +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:175 +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:178 +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:181 +msgid "" +"To use **hatch_vcs** you will need to use the **hatchling** build back " +"end." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:184 +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:189 +msgid "Hatch example setup in your pyproject.toml" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:198 +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:208 +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:211 +msgid "hatch_vcs pros" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:213 +msgid "Hatch supports modern Python packaging standards" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:214 +#: ../../package-structure-code/python-package-versions.md:240 +msgid "It creates a single-source file that contains your package version." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:215 +#: ../../package-structure-code/python-package-versions.md:241 +msgid "You never manually update the package version" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:216 +#: ../../package-structure-code/python-package-versions.md:242 +msgid "" +"You can automate writing the version anywhere in your package including " +"your documentation!" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:217 +#: ../../package-structure-code/python-package-versions.md:243 +msgid "" +"It supports a purely GitHub based release workflow. This simplifies " +"maintenance workflows." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:218 +#: ../../package-structure-code/python-package-versions.md:244 +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:219 +#: ../../package-structure-code/python-package-versions.md:245 +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:221 +msgid "hatch_vcs cons" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:223 +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:226 +msgid "Tool 3: setuptools-scm versioning using git tags" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:228 +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:234 +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:238 +msgid "setuptools_scm Pros" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:246 +msgid "**setuptools** is still the most commonly used Python packaging build tool" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:248 +msgid "setuptools_scm cons" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:250 +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:251 +msgid "Not well documented" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:252 +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:254 +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:266 +msgid "" +"Tool 4: [Python semantic release](https://python-semantic-" +"release.readthedocs.io/en/latest/)" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:268 +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:273 +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:276 +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:286 +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:294 +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:297 +msgid "Python Semantic Release pros" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:299 +msgid "Follows semver versioning closely" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:300 +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:302 +msgid "Python Semantic Release cons" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:304 +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:305 +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:306 +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/pt/LC_MESSAGES/tests.po b/locales/pt/LC_MESSAGES/tests.po new file mode 100644 index 000000000..df1404af1 --- /dev/null +++ b/locales/pt/LC_MESSAGES/tests.po @@ -0,0 +1,1594 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2026, pyOpenSci +# This file is distributed under the same license as the pyOpenSci Python +# Package Guide package. +# FIRST AUTHOR , 2026. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: pyOpenSci Python Package Guide \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-05-18 10:26-0700\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: pt\n" +"Language-Team: pt \n" +"Plural-Forms: nplurals=2; plural=(n != 1);\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.18.0\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:** Parts of your codebase that are not covered " +"by tests." +msgstr "" + +#: ../../tests/code-cov.md:15 +msgid "**Catch bugs:** Bugs that might otherwise go unnoticed." +msgstr "" + +#: ../../tests/code-cov.md:16 +msgid "**Build confidence:** Confidence in your software's stability." +msgstr "" + +#: ../../tests/code-cov.md:18 +msgid "Limitations of code coverage" +msgstr "" + +#: ../../tests/code-cov.md:20 +msgid "While high code coverage is valuable, it has its limits:" +msgstr "" + +#: ../../tests/code-cov.md:22 +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:24 +msgid "" +"**Missed edge cases:** Running all lines of code doesn't guarantee that " +"edge cases are handled correctly." +msgstr "" + +#: ../../tests/code-cov.md:27 +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:30 +msgid "Tools for analyzing Python package code coverage" +msgstr "" + +#: ../../tests/code-cov.md:32 +msgid "" +"Some common services for analyzing code coverage are " +"[codecov.io](https://about.codecov.io/) and " +"[coveralls.io](https://coveralls.io/). These projects are free for open " +"source tools and provide dashboards that show 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:39 +#, python-format +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:44 +msgid "" +"The CodeCov platform is a useful tool if you wish to track code coverage " +"visually. Using it, you can 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](test-types.md#unit-tests) and/or how much of your" +" package code is \"covered\". It, however, will not evaluate things like " +"[integration tests](test-types.md#integration-tests) and [end-to-end " +"workflows](test-types.md)." +msgstr "" + +#: ../../tests/code-cov.md:56 +msgid "Typing & MyPy coverage" +msgstr "" + +#: ../../tests/code-cov.md:57 +msgid "You can also create and upload typing reports to CodeCov." +msgstr "" + +#: ../../tests/code-cov.md:60 +msgid "Exporting Local Coverage Reports" +msgstr "" + +#: ../../tests/code-cov.md:62 +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:67 +msgid "To generate a coverage report in **Markdown** format, run:" +msgstr "" + +#: ../../tests/code-cov.md:73 +msgid "" +"This command will produce a Markdown-formatted coverage summary that you " +"can include in project documentation or share with your team." +msgstr "" + +#: ../../tests/code-cov.md:76 +msgid "" +"To generate an HTML report that provides a detailed, interactive view of " +"which lines are covered, use:" +msgstr "" + +#: ../../tests/code-cov.md:83 +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:87 +msgid "" +"These local reports are an excellent way to quickly review coverage " +"without setting up an external service." +msgstr "" + +#: ../../tests/code-cov.md:90 ../../tests/run-tests-nox.md:168 +#: ../../tests/run-tests.md:332 ../../tests/test-types.md:346 +#: ../../tests/write-tests.md:136 +msgid "Next steps" +msgstr "" + +#: ../../tests/code-cov.md:92 +msgid "" +"Writing meaningful tests is the foundation of useful coverage. See [Write" +" tests](write-tests.md) and [Test types](test-types.md) to learn more " +"about developing better test suites. Learn how to run your tests both " +"[locally](run-tests.md) and in [continuous integration](tests-ci.md)." +msgstr "" + +#: ../../tests/index.md:70 +msgid "Intro" +msgstr "" + +#: ../../tests/index.md:70 +msgid "Write tests" +msgstr "" + +#: ../../tests/index.md:70 +msgid "Test types" +msgstr "" + +#: ../../tests/index.md:70 +msgid "Run tests locally" +msgstr "" + +#: ../../tests/index.md:70 ../../tests/run-tests-nox.md:7 +msgid "Run tests with Nox" +msgstr "" + +#: ../../tests/index.md:70 +msgid "Run tests online (using CI)" +msgstr "" + +#: ../../tests/index.md:70 +msgid "Code coverage" +msgstr "" + +#: ../../tests/index.md:70 +msgid "Create & Run Tests" +msgstr "" + +#: ../../tests/index.md:2 +msgid "Tests and data for your Python package" +msgstr "" + +#: ../../tests/index.md:4 +msgid "" +"Adding tests to your package provides a set of checks that ensure that " +"its functioning how you expect it to." +msgstr "" + +#: ../../tests/index.md:7 +msgid "" +"In this section, you will learn about the importance of writing tests for" +" your Python package, different [types of tests that you should consider" +"](test-types) and how you can set up infrastructure to run your tests " +"both [locally](run-tests) and [on GitHub](tests-ci)." +msgstr "" + +#: ../../tests/index.md:16 +msgid "✨ Why write tests ✨" +msgstr "" + +#: ../../tests/index.md:21 +msgid "" +"Learn about the importance of writing tests for your Python package and " +"how they help you and potential contributors." +msgstr "" + +#: ../../tests/index.md:25 +msgid "✨ Types of tests ✨" +msgstr "" + +#: ../../tests/index.md:30 +msgid "" +"Get to know the three test types: unit, integration, and end-to-end " +"tests. Learn when and how to use each." +msgstr "" + +#: ../../tests/index.md:34 +msgid "✨ Run tests locally ✨" +msgstr "" + +#: ../../tests/index.md:39 +msgid "" +"Learn about testing tools like pytest, nox, and tox to run tests across " +"different Python versions on your computer. And explore examples of using" +" Hatch with UV as a task runner to run tests across Python versions." +msgstr "" + +#: ../../tests/index.md:43 +msgid "✨ Run tests locally (using nox) ✨" +msgstr "" + +#: ../../tests/index.md:48 +msgid "" +"Nox is a python powered task runner that can be used to run tests. Learn " +"how to use nox to run tests." +msgstr "" + +#: ../../tests/index.md:51 +msgid "✨ Run tests online (using CI) ✨" +msgstr "" + +#: ../../tests/index.md:56 +msgid "" +"Set up continuous integration with GitHub Actions to run tests across " +"Python versions and operating systems." +msgstr "" + +#: ../../tests/index.md:60 +msgid "✨ Code coverage ✨" +msgstr "" + +#: ../../tests/index.md:65 +msgid "" +"Measure how much of your package code runs during tests. Learn to " +"generate local reports and visualize coverage online." +msgstr "" + +#: ../../tests/run-tests.md:7 +msgid "Run tests for your Python package" +msgstr "" + +#: ../../tests/run-tests.md:9 +msgid "" +"Running your tests across different Python versions and operating systems" +" is critical to ensuring your package works for your users. Your users " +"may be running different versions of Python and operating systems than " +"you are." +msgstr "" + +#: ../../tests/run-tests.md:13 +msgid "" +"This page teaches you how to run tests locally in isolated environments " +"and across multiple Python versions. You'll learn about two main " +"automation tools: [**Hatch**](https://hatch.pypa.io/) and " +"[**Nox**](https://nox.thea.codes/en/stable/index.html). In the next " +"lesson, you will learn about running your tests online in [continuous " +"integration (CI)](tests-ci)." +msgstr "" + +#: ../../tests/run-tests.md:20 +msgid "Why run tests across multiple environments?" +msgstr "" + +#: ../../tests/run-tests.md:22 +msgid "" +"When you develop a package on your computer, it works in one specific " +"environment: your Python version, your operating system, and your " +"installed dependencies. Your users, however, will run your code in many " +"different environments. By running your tests across multiple Python " +"versions and operating systems, you catch compatibility issues before " +"users do." +msgstr "" + +#: ../../tests/run-tests.md:28 +msgid "" +"Additionally, running tests in isolated environments ensures that your " +"tests pass because of your code, not because of unexpected dependencies " +"installed on your computer. This gives you confidence that your package " +"will work when others install it." +msgstr "" + +#: ../../tests/run-tests.md:33 +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:37 +msgid "**Related pages:**" +msgstr "" + +#: ../../tests/run-tests.md:39 +msgid "[Write tests](write-tests.md) for best practices on writing test suites" +msgstr "" + +#: ../../tests/run-tests.md:41 +msgid "" +"[Test types](test-types.md) to understand unit, integration, and end-to-" +"end tests" +msgstr "" + +#: ../../tests/run-tests.md:43 +msgid "[Run tests online with CI](tests-ci.md) for GitHub Actions setup" +msgstr "" + +#: ../../tests/run-tests.md:44 +msgid "[Code coverage](code-cov.md) to measure how much code your tests cover" +msgstr "" + +#: ../../tests/run-tests.md:48 +msgid "Tools to run your tests" +msgstr "" + +#: ../../tests/run-tests.md:50 +msgid "" +"There are three categories of tools that will make it easier to setup and" +" run your tests in various environments:" +msgstr "" + +#: ../../tests/run-tests.md:53 +msgid "" +"**Testing framework (pytest):** Provides the syntax and tools for writing" +" and running your tests. Learn more from the [pytest " +"documentation](https://docs.pytest.org/). Below you will learn about " +"pytest, the most commonly used testing framework in the scientific Python" +" ecosystem. Testing frameworks are essential for running tests, but they " +"don't provide an easy way to run tests across Python versions or in " +"isolated environments—that's where automation tools come in." +msgstr "" + +#: ../../tests/run-tests.md:61 +msgid "" +"**Automation tools (Nox, Tox, Hatch):** Allow you to run tests in " +"isolated environments and across multiple Python versions with a single " +"command. We focus on [**Hatch**](https://hatch.pypa.io/) and " +"[**Nox**](https://nox.thea.codes/) below. These tools create virtual " +"environments automatically and ensure your tests run consistently. " +"However, they typically only test on your local operating system." +msgstr "" + +#: ../../tests/run-tests.md:69 +msgid "" +"**Continuous Integration (CI):** Runs your tests online across different " +"operating systems (Windows, Mac, and Linux) and Python versions. CI " +"integrates with platforms like GitHub Actions to automatically test every" +" pull request and code change." +msgstr "" + +#: ../../tests/run-tests.md:74 +msgid "[Learn about CI here](ci-cd)." +msgstr "" + +#: ../../tests/run-tests.md:76 +msgid "Quick comparison: what each tool does" +msgstr "" + +#: ../../tests/run-tests.md:78 +msgid "**Testing Framework (pytest):**" +msgstr "" + +#: ../../tests/run-tests.md:80 +msgid "Runs your tests locally in your current Python environment" +msgstr "" + +#: ../../tests/run-tests.md:81 +msgid "Provides the core syntax for writing tests (assertions, fixtures, etc.)" +msgstr "" + +#: ../../tests/run-tests.md:83 +msgid "Can be extended with plugins (like pytest-cov for coverage)" +msgstr "" + +#: ../../tests/run-tests.md:85 +msgid "**Automation Tools (Nox, Tox, Hatch):**" +msgstr "" + +#: ../../tests/run-tests.md:87 +msgid "Run tests locally across multiple Python versions" +msgstr "" + +#: ../../tests/run-tests.md:88 +msgid "Create and manage isolated virtual environments automatically" +msgstr "" + +#: ../../tests/run-tests.md:89 +msgid "Can automate other tasks like building documentation" +msgstr "" + +#: ../../tests/run-tests.md:90 +msgid "Make it easy to reproduce test environments" +msgstr "" + +#: ../../tests/run-tests.md:92 +msgid "**Continuous Integration (GitHub Actions):**" +msgstr "" + +#: ../../tests/run-tests.md:94 +msgid "Runs tests online automatically for every pull request" +msgstr "" + +#: ../../tests/run-tests.md:95 +msgid "Tests across different operating systems (Windows, Mac, Linux)" +msgstr "" + +#: ../../tests/run-tests.md:96 +msgid "Tests across multiple Python versions in parallel" +msgstr "" + +#: ../../tests/run-tests.md:97 +msgid "Can automate deployments, releases, and other workflows" +msgstr "" + +#: ../../tests/run-tests.md:99 +msgid "What testing framework / package should I use to run tests?" +msgstr "" + +#: ../../tests/run-tests.md:101 +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:103 +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:106 +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://about.codecov.io/)." +msgstr "" + +#: ../../tests/run-tests.md:108 ../../tests/tests-ci.md:7 +msgid "Todo" +msgstr "" + +#: ../../tests/run-tests.md:109 +msgid "Learn more about code coverage here. (add link)" +msgstr "" + +#: ../../tests/run-tests.md:113 +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:116 +msgid "Run tests using pytest" +msgstr "" + +#: ../../tests/run-tests.md:118 +msgid "If you are using **pytest**, you can run your tests locally by calling:" +msgstr "" + +#: ../../tests/run-tests.md:121 +msgid "`pytest`" +msgstr "" + +#: ../../tests/run-tests.md:123 +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:125 +msgid "`pytest test_module.py`" +msgstr "" + +#: ../../tests/run-tests.md:127 +msgid "" +"Learn more about pytest [here](https://docs.pytest.org/en/stable/getting-" +"started.html)." +msgstr "" + +#: ../../tests/run-tests.md:129 +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:134 +msgid "" +"An automation tool can simplify the process of running tests in various " +"Python environments." +msgstr "" + +#: ../../tests/run-tests.md:137 +msgid "Tests across operating systems" +msgstr "" + +#: ../../tests/run-tests.md:138 +msgid "" +"If you want to run your tests on different operating systems you can use " +"continuous integration. [Learn more here](tests-ci)." +msgstr "" + +#: ../../tests/run-tests.md:141 +msgid "Tools to automate running your tests" +msgstr "" + +#: ../../tests/run-tests.md:143 +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:146 +msgid "" +"We will focus on Hatch on this page as Hatch is the default tool that we " +"use in our [tutorials](create-pure-python-package) and for our [Python " +"package template](https://github.com/pyOpenSci/pyos-package-template)." +msgstr "" + +#: ../../tests/run-tests.md:149 +msgid "" +"If you are not a hatch fan, then [Nox](https://nox.thea.codes/) is an " +"alternative tool that we cover in the next lesson. `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. You will learn more about " +"using nox [here](run-tests-nox)." +msgstr "" + +#: ../../tests/run-tests.md:151 +msgid "Other automation tools you'll see in the wild" +msgstr "" + +#: ../../tests/run-tests.md:154 +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:159 +msgid "" +"**[Make](https://www.gnu.org/software/make/manual/make.html)** is a build" +" automation tool that some developers use for running tests due to its " +"versatility. However, Make's unique syntax can be challenging to learn, " +"and it won't manage environments for you like Hatch and Nox do." +msgstr "" + +#: ../../tests/run-tests.md:166 +msgid "Run tests with Hatch" +msgstr "" + +#: ../../tests/run-tests.md:168 +msgid "" +"**Hatch** is a modern Python packaging and environment manager that " +"integrates test running capabilities directly into your `pyproject.toml`." +" Unlike Nox (which uses a separate `noxfile.py`), Hatch keeps all your " +"project configuration in one place, making it ideal if you're already " +"using Hatch for packaging workflows." +msgstr "" + +#: ../../tests/run-tests.md:174 +msgid "Why Hatch for testing?" +msgstr "" + +#: ../../tests/run-tests.md:176 +msgid "Configuration lives in `pyproject.toml` alongside your project metadata" +msgstr "" + +#: ../../tests/run-tests.md:178 +msgid "Integrates seamlessly with Hatch's packaging and build workflows" +msgstr "" + +#: ../../tests/run-tests.md:179 +msgid "No separate Python file needed (unlike Nox)" +msgstr "" + +#: ../../tests/run-tests.md:180 +msgid "Easy to share standardized test environments across your team" +msgstr "" + +#: ../../tests/run-tests.md:182 +msgid "Setting up Hatch environments" +msgstr "" + +#: ../../tests/run-tests.md:184 +msgid "" +"Hatch environments are defined in your `pyproject.toml`. Rather than " +"duplicating dependencies, use `dependency-groups` to reference your test " +"dependencies:" +msgstr "" + +#: ../../tests/run-tests.md:205 +msgid "" +"This approach keeps your test dependencies in one place and avoids " +"duplication. For a complete example, see our [packaging template " +"tutorial](https://www.pyopensci.org/tutorials/create-python-package.html)" +" which shows a full `pyproject.toml` configuration." +msgstr "" + +#: ../../tests/run-tests.md:210 +msgid "Running tests with Hatch" +msgstr "" + +#: ../../tests/run-tests.md:212 +msgid "" +"Once you've defined your test environment, you can run tests with simple " +"commands:" +msgstr "" + +#: ../../tests/run-tests.md:215 +msgid "**List available environments:**" +msgstr "" + +#: ../../tests/run-tests.md:221 +msgid "**Run pytest in the test environment:**" +msgstr "" + +#: ../../tests/run-tests.md:228 +msgid "Testing across Python versions" +msgstr "" + +#: ../../tests/run-tests.md:230 +msgid "" +"To test across multiple Python versions, define a matrix in your " +"`pyproject.toml`:" +msgstr "" + +#: ../../tests/run-tests.md:249 +msgid "Then run all versions with a single command:" +msgstr "" + +#: ../../tests/run-tests.md:255 +msgid "" +"Hatch will automatically run your tests on Python 3.10, 3.11, and 3.12. " +"If you only want to test a specific Python version:" +msgstr "" + +#: ../../tests/run-tests.md:262 +msgid "Using Hatch in GitHub Actions" +msgstr "" + +#: ../../tests/run-tests.md:264 +msgid "Hatch integrates well with CI/CD. Here's a minimal GitHub Actions setup:" +msgstr "" + +#: ../../tests/run-tests.md:288 +msgid "" +"Since all of your test dependencies are declared in the `dependency-" +"group` table of your `pyproject.toml`, your CI environment is " +"reproducible and consistent with the environments that you are using for " +"local testing." +msgstr "" + +#: ../../tests/run-tests.md:292 +msgid "Nox vs Hatch: choosing the right tool" +msgstr "" + +#: ../../tests/run-tests.md:294 +msgid "" +"Both Hatch and Nox are excellent automation tools / task runners for " +"running tests across Python versions. Here's how they compare to help you" +" decide which fits your workflow:" +msgstr "" + +#: ../../tests/run-tests.md:298 +msgid "Hatch" +msgstr "" + +#: ../../tests/run-tests.md:300 +msgid "" +"**Configuration:** Hatch uses a `declarative` configuration approach. You" +" tell it what goes into an environment and that empowers Hatch to create " +"the environment for you. All configuration settings live in your " +"`pyproject.toml` alongside your project metadata" +msgstr "" + +#: ../../tests/run-tests.md:302 +msgid "" +"**Integration:** Hatch is package management tool that also has an " +"integrated automation / task runner. Using Hatch means you are using the " +"same tool for all of your packaging and automation needs." +msgstr "" + +#: ../../tests/run-tests.md:303 +msgid "" +"**Learning curve:** Easier if you prefer declarative configuration over a" +" code based workflow" +msgstr "" + +#: ../../tests/run-tests.md:304 +msgid "" +"**packaging scope** Hatch is better for simpler workflows that focus on " +"testing and packaging. If you have more complex builds or are creating a " +"non pure python package you might prefer Nox. The scientific Python " +"development guide has more details on this." +msgstr "" + +#: ../../tests/run-tests.md:305 +msgid "" +"**Best for:** Teams using Hatch for packaging, or those who want " +"standardized configuration in one place" +msgstr "" + +#: ../../tests/run-tests.md:308 +msgid "Nox" +msgstr "" + +#: ../../tests/run-tests.md:310 +msgid "**Configuration:** Python-driven via `noxfile.py` for maximum flexibility" +msgstr "" + +#: ../../tests/run-tests.md:311 +msgid "**Customization:** Great for complex workflows that need custom logic" +msgstr "" + +#: ../../tests/run-tests.md:312 +msgid "" +"**Learning curve:** Easier if you already know Python and want flexible " +"session control" +msgstr "" + +#: ../../tests/run-tests.md:314 +msgid "" +"**Best for:** Complex automation needs, building docs alongside tests, or" +" workflows that don't fit the standard model" +msgstr "" + +#: ../../tests/run-tests.md:317 +msgid "What we recommend" +msgstr "" + +#: ../../tests/run-tests.md:319 +msgid "" +"**If you're using Hatch for packaging:** Use Hatch for testing too. You " +"get everything in one place and one consistent tool." +msgstr "" + +#: ../../tests/run-tests.md:322 +msgid "" +"**If you need maximum flexibility:** Choose Nox. Its Python-driven " +"approach lets you implement almost any workflow." +msgstr "" + +#: ../../tests/run-tests.md:325 +msgid "" +"**If you're just starting out:** Start with Hatch. It's simpler to set up" +" and understand, and you can always switch to Nox later if you need to." +msgstr "" + +#: ../../tests/run-tests.md:328 +msgid "" +"**Both tools are good choices.** For a more comprehensive guide to using" +" Nox, see [Run tests with Nox](run-tests-nox.md) and the [Scientific " +"Python testing guide](https://scientific-python.org/tools/testing)." +msgstr "" + +#: ../../tests/run-tests.md:334 +msgid "" +"Now that you understand how to run tests locally across Python versions, " +"you can learn about [running tests automatically in GitHub Actions with " +"continuous integration](tests-ci). You can also review [test types](test-" +"types) and [write tests](write-tests) for your package." +msgstr "" + +#: ../../tests/run-tests-nox.md:9 +msgid "" +"**Nox** is a Python-based automation tool for running tests across " +"multiple Python versions and managing isolated test environments. If you " +"prefer Python-driven configuration over TOML, or need complex automation " +"workflows, Nox is an excellent choice." +msgstr "" + +#: ../../tests/run-tests-nox.md:14 +msgid "" +"For more information about Nox, see the [official Nox " +"documentation](https://nox.thea.codes/) or the [Scientific Python guide " +"to testing](https://scientific-python.org/tools/testing)." +msgstr "" + +#: ../../tests/run-tests-nox.md:18 +msgid "Why Nox?" +msgstr "" + +#: ../../tests/run-tests-nox.md:20 +msgid "**Nox** is a great automation tool because it:" +msgstr "" + +#: ../../tests/run-tests-nox.md:22 +msgid "Is Python-based, making it accessible if you already know Python" +msgstr "" + +#: ../../tests/run-tests-nox.md:23 +msgid "Will create isolated environments to run workflows" +msgstr "" + +#: ../../tests/run-tests-nox.md:24 +msgid "Supports complex, custom automation beyond standard testing" +msgstr "" + +#: ../../tests/run-tests-nox.md:25 +msgid "Is flexible and powerful for intricate build and test scenarios" +msgstr "" + +#: ../../tests/run-tests-nox.md:27 +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-nox.md:31 +msgid "Set up Nox" +msgstr "" + +#: ../../tests/run-tests-nox.md:33 +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." +msgstr "" + +#: ../../tests/run-tests-nox.md:37 +msgid "Nox installations" +msgstr "" + +#: ../../tests/run-tests-nox.md:39 +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. Nox will manage" +" each environment on its own." +msgstr "" + +#: ../../tests/run-tests-nox.md:45 +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-nox.md:50 +msgid "Test environments" +msgstr "" + +#: ../../tests/run-tests-nox.md:52 +msgid "" +"By default, `nox` uses Python's 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-nox.md:58 +msgid "Nox with venv environments" +msgstr "" + +#: ../../tests/run-tests-nox.md:60 +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-nox.md:63 +msgid "" +"Note that the example below assumes that you have setup your " +"`pyproject.toml` to declare test dependencies using `project.optional-" +"dependencies`:" +msgstr "" + +#: ../../tests/run-tests-nox.md:83 +msgid "" +"With this setup, 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-nox.md:89 +msgid "" +"For this to run you will need to have python3.9, python3.10, python3.11, " +"and python3.12 installed on your computer. Otherwise nox will skip " +"running tests for whatever versions are missing." +msgstr "" + +#: ../../tests/run-tests-nox.md:107 +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-nox.md:111 +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-nox.md:119 +msgid "Nox with conda / mamba" +msgstr "" + +#: ../../tests/run-tests-nox.md:121 +msgid "" +"Below is an example for setting up Nox to use mamba (or conda) for your " +"environment manager. 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-nox.md:127 +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-nox.md:150 +msgid "To run the above session you'd use:" +msgstr "" + +#: ../../tests/run-tests-nox.md:156 +msgid "Hatch vs Nox" +msgstr "" + +#: ../../tests/run-tests-nox.md:158 +msgid "" +"If you're trying to decide between Hatch and Nox, see the [comparison and" +" recommendations on the main testing page](run-tests.md)." +msgstr "" + +#: ../../tests/run-tests-nox.md:161 +msgid "In summary" +msgstr "" + +#: ../../tests/run-tests-nox.md:163 +msgid "" +"**Choose Hatch** if you're already using Hatch for packaging and want " +"everything in one place" +msgstr "" + +#: ../../tests/run-tests-nox.md:165 +msgid "" +"**Choose Nox** if you need maximum flexibility, prefer Python-driven " +"configuration, or need complex automation workflows" +msgstr "" + +#: ../../tests/run-tests-nox.md:170 +msgid "" +"Now that you understand how to run tests locally with Nox, you can learn " +"about [running tests automatically with continuous integration](tests-ci)" +" or [running tests with Hatch](run-tests.md)." +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, and 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 ../../tests/test-types.md:15 +msgid "Unit tests" +msgstr "" + +#: ../../tests/test-types.md:9 ../../tests/test-types.md:93 +msgid "Integration tests" +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 by working through simple examples." +msgstr "" + +#: ../../tests/test-types.md:17 +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:22 +msgid "" +"Unit tests can be compared to examining each piece of your puzzle to " +"ensure parts or subsections of it are not broken. If all of the pieces of" +" that section of your puzzle don't fit together, you will never complete " +"it. Similarly, when working with code, tests ensure that each function, " +"attribute, class, and method works properly when isolated." +msgstr "" + +#: ../../tests/test-types.md:28 +msgid "" +"**Unit test example:** Suppose you have a function that adds two numbers " +"together. A unit test for that function ensures that when provided with " +"two numbers, it returns the correct sum. This is a unit test because it " +"checks a single unit (function) in isolation." +msgstr "" + +#: ../../tests/test-types.md:54 +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:76 +msgid "" +"Notice that the tests above don't just test one case where numbers are " +"added together. Instead, they test multiple scenarios: adding positive " +"numbers, adding a negative number, and adding zero. This helps ensure " +"that the `add_numbers` function behaves correctly in different situations" +" and is the beginning of thinking about programming defensively." +msgstr "" + +#: ../../tests/test-types.md:83 +msgid "" +"You can run this test from your terminal using `pytest " +"tests/test_math_utils.py`." +msgstr "" + +#: ../../tests/test-types.md:86 ../../tests/test-types.md:215 +msgid "" +"image of puzzle pieces that all fit together nicely. The puzzle pieces " +"are colorful - purple, green and teal." +msgstr "" + +#: ../../tests/test-types.md:90 +msgid "" +"Your unit tests should ensure each part of your code works as expected on" +" its own." +msgstr "" + +#: ../../tests/test-types.md:95 +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:100 +msgid "" +"For example, suppose you have functions that convert temperatures and " +"calculate statistics. An integration test would ensure that these " +"functions work together correctly in a workflow where you convert " +"temperatures and then analyze them." +msgstr "" + +#: ../../tests/test-types.md:178 +msgid "" +"Here's an integration test that checks how the conversion and statistics " +"functions work together:" +msgstr "" + +#: ../../tests/test-types.md:204 +msgid "" +"This integration test verifies that the conversion and averaging " +"functions work together as expected in a real workflow." +msgstr "" + +#: ../../tests/test-types.md:207 +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:212 +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:220 +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:224 +msgid "End-to-end (functional) tests" +msgstr "" + +#: ../../tests/test-types.md:226 +msgid "" +"End-to-end tests (also referred to as functional tests) in Python are " +"like comprehensive checklists for your software. They simulate real user " +"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 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 " +"user experience." +msgstr "" + +#: ../../tests/test-types.md:235 +msgid "Image of a completed puzzle showing a daisy" +msgstr "" + +#: ../../tests/test-types.md:240 +msgid "" +"End-to-end or functional tests represent an entire workflow that your " +"package supports." +msgstr "" + +#: ../../tests/test-types.md:244 +msgid "" +"**End-to-end test example:** Let's say your package opens and " +"processes/converts temperature data from Celsius to Fahrenheit and then " +"calculates the average temperature. An end-to-end test would simulate " +"this entire workflow, ensuring that the package correctly handles the " +"input temperature data and returns a summary average value. An end-to-end" +" test would provide sample data, run the entire workflow, and verify that" +" the final output is correct." +msgstr "" + +#: ../../tests/test-types.md:274 +msgid "" +"This end-to-end test exercises the entire user workflow: providing sample" +" data, converting and averaging it, and verifying the output is correct." +msgstr "" + +#: ../../tests/test-types.md:278 +msgid "" +"End-to-end tests also verify how a program runs from start to finish. A " +"tutorial that you add to your documentation and run in CI is another " +"example of an end-to-end test. For example, a Jupyter (`.ipynb`) notebook" +" or `.md` file with embedded code that demonstrates a complete user " +"workflow." +msgstr "" + +#: ../../tests/test-types.md:285 +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:290 +msgid "When to use which test type" +msgstr "" + +#: ../../tests/test-types.md:292 +msgid "" +"If you’re new to testing, start with unit tests. They are the simplest to" +" write, fastest to run, and easiest to debug. As your package grows, you " +"can then add integration and end-to-end tests where they add the most " +"value." +msgstr "" + +#: ../../tests/test-types.md:294 +msgid "Start by writing unit tests" +msgstr "" + +#: ../../tests/test-types.md:296 +msgid "Are you testing a single function, method, or class in isolation?" +msgstr "" + +#: ../../tests/test-types.md:298 +msgid "→ Yes: Write a [unit test](test-types.md#unit-tests)." +msgstr "" + +#: ../../tests/test-types.md:300 +msgid "Example: Check that add_numbers(2, 3) returns 5" +msgstr "" + +#: ../../tests/test-types.md:301 +msgid "Unit tests don’t rely on other parts of your code" +msgstr "" + +#: ../../tests/test-types.md:302 +msgid "These tests form the foundation of your test suite" +msgstr "" + +#: ../../tests/test-types.md:303 +msgid "If something breaks, unit tests make it easy to find where" +msgstr "" + +#: ../../tests/test-types.md:305 +msgid "Add integration tests next" +msgstr "" + +#: ../../tests/test-types.md:307 +msgid "Are you testing how multiple components work together?" +msgstr "" + +#: ../../tests/test-types.md:309 +msgid "→ **Yes:** Write [integration tests](test-types.md#integration-tests)." +msgstr "" + +#: ../../tests/test-types.md:311 +msgid "Example: Converting temperatures and then computing their average" +msgstr "" + +#: ../../tests/test-types.md:312 +msgid "Integration tests assume individual pieces already work" +msgstr "" + +#: ../../tests/test-types.md:313 +msgid "These tests verify that components interact correctly" +msgstr "" + +#: ../../tests/test-types.md:315 +msgid "Use end-to-end tests for core workflows" +msgstr "" + +#: ../../tests/test-types.md:317 +msgid "Are you testing a complete, realistic user workflow from start to finish?" +msgstr "" + +#: ../../tests/test-types.md:319 +msgid "" +"→ **Yes:** Use an [end-to-end test](test-types.md#end-to-end-functional-" +"tests)." +msgstr "" + +#: ../../tests/test-types.md:321 +msgid "Example: Run a full data-processing workflow a user would follow" +msgstr "" + +#: ../../tests/test-types.md:322 +msgid "These tests often mirror examples in your documentation" +msgstr "" + +#: ../../tests/test-types.md:323 +msgid "Use them sparingly for the most important workflows." +msgstr "" + +#: ../../tests/test-types.md:324 +msgid "Tutorials run during documentation builds can serve as end-to-end tests." +msgstr "" + +#: ../../tests/test-types.md:326 +msgid "Comparing unit, integration, and end-to-end tests" +msgstr "" + +#: ../../tests/test-types.md:328 +msgid "" +"Unit tests, integration tests, and end-to-end tests have complementary " +"advantages and disadvantages. The fine-grained nature of unit tests makes" +" 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:334 +msgid "" +"Integration and end-to-end tests verify that different portions of the " +"program work together, but are less valuable for immediately isolating " +"exactly where errors are occurring." +msgstr "" + +#: ../../tests/test-types.md:338 +msgid "Tests don't have to be perfect" +msgstr "" + +#: ../../tests/test-types.md:339 +msgid "" +"It is important to note that you don't need to spend energy worrying " +"about the specifics of test types. When you begin to work on your test " +"suite, consider what your package does and how you may need to test parts" +" of it. Being familiar with different test types provides a framework to " +"help you think about writing tests and how they can complement each " +"other." +msgstr "" + +#: ../../tests/test-types.md:348 +msgid "" +"Now that you understand test types, learn how to [write effective tests" +"](write-tests) for your package. Then explore how to [run tests locally" +"](run-tests) and in [continuous integration](tests-ci). You can also " +"learn about tracking test coverage using tools like [CodeCov](code-cov)." +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:9 +msgid "Why write tests for your package?" +msgstr "" + +#: ../../tests/write-tests.md:11 +msgid "" +"Tests act as a safety net for code changes. They help you identify and " +"fix bugs before they affect users. Tests also instill confidence that " +"code changes from contributors won't break existing functionality." +msgstr "" + +#: ../../tests/write-tests.md:15 +msgid "Writing tests for your Python package is important because:" +msgstr "" + +#: ../../tests/write-tests.md:17 +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:20 +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:23 +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:27 +msgid "" +"**Fearless refactoring:** Refactoring means making improvements to your " +"code structure without changing its behavior. Tests empower you to make " +"these changes; if you break something, test failures will let you know." +msgstr "" + +#: ../../tests/write-tests.md:30 +msgid "" +"**Documentation:** Tests serve as technical examples of how to use your " +"package. This can be helpful for new technical contributors who want 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:34 +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:38 +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:44 +msgid "Tests for user edge cases" +msgstr "" + +#: ../../tests/write-tests.md:46 +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:55 +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:59 +msgid "Test examples" +msgstr "" + +#: ../../tests/write-tests.md:62 +msgid "Let's say you have a Python function that adds two numbers together." +msgstr "" + +#: ../../tests/write-tests.md:84 +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:103 +msgid "🧩🐍 How do you know what type of tests to write?" +msgstr "" + +#: ../../tests/write-tests.md:105 +msgid "As you begin to write tests for your package, you should consider:" +msgstr "" + +#: ../../tests/write-tests.md:107 +msgid "" +"there are [three types of tests Test Types for Python Packages](test-" +"types.md) that can help guide your development." +msgstr "" + +#: ../../tests/write-tests.md:108 +msgid "" +"your tests should consider how a user might use (and misuse!) your " +"package." +msgstr "" + +#: ../../tests/write-tests.md:111 +msgid "" +"This section has been adapted from [a presentation by Nick " +"Murphy](https://zenodo.org/records/8185113)." +msgstr "" + +#: ../../tests/write-tests.md:115 +msgid "But, what should you be testing in your package? Below are a few examples:" +msgstr "" + +#: ../../tests/write-tests.md:118 +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:123 +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 of 0, test it with the input of both 0 " +"and nearby values." +msgstr "" + +#: ../../tests/write-tests.md:128 +msgid "" +"**Test at and near expected boundaries:** If a function requires a value " +"that is greater than or equal to 1, make sure that the function still " +"works with the values 1 and 0.999, as well as 1.001 (values close to the " +"constraint). Make sure that the function fails gracefully when given " +"unexpected values and that the user can easily understand why it failed " +"by providing a useful error message." +msgstr "" + +#: ../../tests/write-tests.md:138 +msgid "" +"Now that you understand what and why to test, explore the [three types of" +" tests](test-types.md) (unit, integration, and end-to-end) to determine " +"which style of tests best fits your package. Then, learn how to [run your" +" tests locally](run-tests.md) and [in continuous integration](tests-" +"ci.md). Finally, track your progress with [code coverage](code-cov.md) " +"metrics." +msgstr "" diff --git a/locales/pt/LC_MESSAGES/tutorials.po b/locales/pt/LC_MESSAGES/tutorials.po new file mode 100644 index 000000000..f247368b3 --- /dev/null +++ b/locales/pt/LC_MESSAGES/tutorials.po @@ -0,0 +1,6885 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2026, pyOpenSci +# This file is distributed under the same license as the pyOpenSci Python +# Package Guide package. +# FIRST AUTHOR , 2026. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: pyOpenSci Python Package Guide \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-05-18 10:26-0700\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: pt\n" +"Language-Team: pt \n" +"Plural-Forms: nplurals=2; plural=(n != 1);\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.18.0\n" + +#: ../../tutorials/add-license-coc.md:6 +msgid "Add a `LICENSE` & `CODE_OF_CONDUCT` to your Python package" +msgstr "" + +#: ../../tutorials/add-license-coc.md:8 +msgid "In the [previous lesson](add-readme) you:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:10 +msgid "" +" " +"Created a basic `README.md` file for your scientific Python package" +msgstr "" + +#: ../../tutorials/add-license-coc.md:12 +msgid "" +" " +"Learned about the core components that are useful to have in a `README` " +"file." +msgstr "" + +#: ../../tutorials/add-license-coc.md:14 ../../tutorials/add-readme.md:15 +msgid "Learning objectives" +msgstr "" + +#: ../../tutorials/add-license-coc.md:17 ../../tutorials/add-readme.md:17 +#: ../../tutorials/pyproject-toml.md:30 +msgid "In this lesson you will learn:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:19 +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:20 +msgid "How to add a `CODE_OF_CONDUCT` file to your package repository." +msgstr "" + +#: ../../tutorials/add-license-coc.md:21 +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:24 +msgid "What is a license?" +msgstr "" + +#: ../../tutorials/add-license-coc.md:26 +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:28 +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:29 +msgid "" +"Describe your choice of license in your `pyproject.toml` data where " +"metadata are set." +msgstr "" + +#: ../../tutorials/add-license-coc.md:31 +msgid "" +"By adding this metadata to your [pyproject.toml](pyproject-toml) file, " +"the choice of license will be included in your package's metadata which " +"is used to populate your package's PyPI landing page. The `LICENSE` file " +"is also used in your GitHub repository's landing page interface, and " +"makes its way into your distributions." +msgstr "" + +#: ../../tutorials/add-license-coc.md:36 +msgid "What license should you use?" +msgstr "" + +#: ../../tutorials/add-license-coc.md:38 +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-Clause[^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:41 +msgid "Licenses for the scientific Python ecosystem" +msgstr "" + +#: ../../tutorials/add-license-coc.md:42 +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:45 +msgid "Where should the `LICENSE` file live" +msgstr "" + +#: ../../tutorials/add-license-coc.md:47 +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:53 +msgid "" +"Image showing the GitHub repository for SunPy an accepted pyOpenSci " +"package." +msgstr "" + +#: ../../tutorials/add-license-coc.md:55 +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:62 +msgid "How to add a `LICENSE` file to your package directory" +msgstr "" + +#: ../../tutorials/add-license-coc.md:64 +msgid "There are several ways to add a `LICENSE` file:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:66 +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:67 +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:68 +msgid "You can add the file manually as we are doing in this lesson." +msgstr "" + +#: ../../tutorials/add-license-coc.md:71 +msgid "If you completed the past lessons including" +msgstr "" + +#: ../../tutorials/add-license-coc.md:73 +msgid "[Making your code installable](create-python-package.md) and" +msgstr "" + +#: ../../tutorials/add-license-coc.md:74 +msgid "[publishing your package to PyPI](publish-pypi.md)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:76 +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:78 +msgid "" +"If you don't yet have a `LICENSE` file in your directory, then continue " +"reading." +msgstr "" + +#: ../../tutorials/add-license-coc.md:81 +msgid "How to add a `LICENSE` to your package - the manual way" +msgstr "" + +#: ../../tutorials/add-license-coc.md:83 +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:85 +msgid "Create a new file called `LICENSE`. If you are using shell you can type:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:92 +msgid "Go to [choosealicense.com](https://choosealicense.com/)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:93 +msgid "Select permissive license" +msgstr "" + +#: ../../tutorials/add-license-coc.md:94 +msgid "" +"It will suggest that you use the [MIT " +"license](https://choosealicense.com/licenses/mit/)." +msgstr "" + +#: ../../tutorials/add-license-coc.md:95 +msgid "" +"Copy the license text that it provides into your `LICENSE` file that you " +"created above." +msgstr "" + +#: ../../tutorials/add-license-coc.md:96 +msgid "Save your file. You're all done!" +msgstr "" + +#: ../../tutorials/add-license-coc.md:98 +msgid "An overview of licenses in the scientific Python ecosystem" +msgstr "" + +#: ../../tutorials/add-license-coc.md:101 +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:103 +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 +msgid "Instructions for adding a `LICENSE` file within the GitHub interface" +msgstr "" + +#: ../../tutorials/add-license-coc.md +msgid "Add license: new GitHub repository" +msgstr "" + +#: ../../tutorials/add-license-coc.md:114 +msgid "" +"When you create a new GitHub repository you can add a `LICENSE` file " +"through the GitHub interface." +msgstr "" + +#: ../../tutorials/add-license-coc.md:119 +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:121 +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 +msgid "Add `LICENSE`: Existing GitHub repository" +msgstr "" + +#: ../../tutorials/add-license-coc.md:127 +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:129 +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:130 +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:133 +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:135 +msgid "" +"You can view a summary of the `LICENSE` chosen on your project's GitHub " +"landing page." +msgstr "" + +#: ../../tutorials/add-license-coc.md:142 +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:147 +msgid "What is a code of conduct file?" +msgstr "" + +#: ../../tutorials/add-license-coc.md:149 +#, python-brace-format +msgid "" +"A `CODE_OF_CONDUCT` file is a {term}`Code of conduct` used to establish " +"guidelines for how people in your community interact." +msgstr "" + +#: ../../tutorials/add-license-coc.md:152 +msgid "" +"This file is critical to supporting your community as it grows. The " +"`CODE_OF_CONDUCT`:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:155 +msgid "" +"Establishes guidelines for how users and contributors interact with each " +"other and you in your software repository." +msgstr "" + +#: ../../tutorials/add-license-coc.md:156 +msgid "Identifies negative behaviors that you don't want in your interactions." +msgstr "" + +#: ../../tutorials/add-license-coc.md:158 +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:160 +msgid "What to put in your `CODE_OF_CONDUCT` file" +msgstr "" + +#: ../../tutorials/add-license-coc.md:162 +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:165 +msgid "" +"![Contributor " +"Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:165 +msgid "Contributor Covenant" +msgstr "" + +#: ../../tutorials/add-license-coc.md:167 +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:169 +msgid "How to add a `CODE_OF_CONDUCT` file to your package directory" +msgstr "" + +#: ../../tutorials/add-license-coc.md:171 +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:177 +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:179 +msgid "That's it - you've now added a code of conduct to your package directory." +msgstr "" + +#: ../../tutorials/add-license-coc.md:181 +msgid "Additional Code of Conduct resources" +msgstr "" + +#: ../../tutorials/add-license-coc.md:184 +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:185 +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:188 ../../tutorials/add-readme.md:240 +#: ../../tutorials/publish-conda-forge.md:475 +#: ../../tutorials/pyproject-toml.md:699 +msgid " Wrap up" +msgstr "" + +#: ../../tutorials/add-license-coc.md:190 +msgid "In this lesson and the [last lesson](add-readme), you have added a:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:192 +msgid "`README` file;" +msgstr "" + +#: ../../tutorials/add-license-coc.md:193 +msgid "`LICENSE` file and a" +msgstr "" + +#: ../../tutorials/add-license-coc.md:194 +msgid "`CODE_OF_CONDUCT` file." +msgstr "" + +#: ../../tutorials/add-license-coc.md:196 +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:200 +#: ../../tutorials/create-python-package.md:455 +msgid "In the upcoming lessons, you will:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:202 +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:203 +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:208 +#: ../../tutorials/create-python-package.md:550 +#: ../../tutorials/publish-conda-forge.md:487 +#: ../../tutorials/publish-pypi.md:419 +#: ../../tutorials/trusted-publishing.md:347 +msgid "Footnotes" +msgstr "" + +#: ../../tutorials/add-license-coc.md:210 +msgid "https://opensource.org/license/mit/" +msgstr "" + +#: ../../tutorials/add-license-coc.md:211 +msgid "https://opensource.org/license/bsd-3-clause/" +msgstr "" + +#: ../../tutorials/add-readme.md:6 +#, python-brace-format +msgid "Add a {term}`README` file to your {term}`Python package`" +msgstr "" + +#: ../../tutorials/add-readme.md:8 +msgid "In the previous lessons you learned:" +msgstr "" + +#: ../../tutorials/add-readme.md:10 +msgid "[What a Python package is](intro.md)" +msgstr "" + +#: ../../tutorials/add-readme.md:11 +msgid "[How to make your code installable](create-python-package)" +msgstr "" + +#: ../../tutorials/add-readme.md:12 +msgid "[How to publish your package to (test) PyPI](publish-pypi.md)" +msgstr "" + +#: ../../tutorials/add-readme.md:13 +msgid "[How to publish your package to conda-forge](publish-conda-forge.md)" +msgstr "" + +#: ../../tutorials/add-readme.md:19 +msgid "How to add a **README.md** file to your package." +msgstr "" + +#: ../../tutorials/add-readme.md:20 +msgid "What the core elements of a **README.md** file are." +msgstr "" + +#: ../../tutorials/add-readme.md:23 +msgid "What is a README file?" +msgstr "" + +#: ../../tutorials/add-readme.md:25 +#, python-brace-format +msgid "" +"The `README.md` file is the project's {term}`README` and is located at " +"the root of your project directory. It helps a user understand:" +msgstr "" + +#: ../../tutorials/add-readme.md:29 +msgid "You package's name" +msgstr "" + +#: ../../tutorials/add-readme.md:30 +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:31 +msgid "The current development \"state\" of the package (through badges)" +msgstr "" + +#: ../../tutorials/add-readme.md:32 +msgid "How to get started with using your package." +msgstr "" + +#: ../../tutorials/add-readme.md:33 +msgid "How to contribute to your package" +msgstr "" + +#: ../../tutorials/add-readme.md:34 +msgid "How to cite your package" +msgstr "" + +#: ../../tutorials/add-readme.md:36 +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:38 +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:42 +msgid "Create a README.md file for your package" +msgstr "" + +#: ../../tutorials/add-readme.md:44 +msgid "It's time to add a `README.md` file to your project directory." +msgstr "" + +#: ../../tutorials/add-readme.md:46 +msgid "Step 0: Create a README file" +msgstr "" + +#: ../../tutorials/add-readme.md:47 +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:50 +msgid "If you created your project directory from" +msgstr "" + +#: ../../tutorials/add-readme.md:52 +msgid "a GitHub repository online" +msgstr "" + +#: ../../tutorials/add-readme.md:53 +msgid "using `hatch init`" +msgstr "" + +#: ../../tutorials/add-readme.md:55 +msgid "Then you may already have a README.MD file in your project directory." +msgstr "" + +#: ../../tutorials/add-readme.md:61 +msgid "Step 1: Add the name of your package as the README title" +msgstr "" + +#: ../../tutorials/add-readme.md:63 +msgid "At the top of the `README.md` file, add the name of your package." +msgstr "" + +#: ../../tutorials/add-readme.md:65 +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:67 +msgid "`# Package-title-here`" +msgstr "" + +#: ../../tutorials/add-readme.md:69 +msgid "Step 2: add badges to the top of your README file" +msgstr "" + +#: ../../tutorials/add-readme.md:71 +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:73 +msgid "Broken documentation and test builds." +msgstr "" + +#: ../../tutorials/add-readme.md:74 +msgid "Versions of your package that are on PyPI and conda." +msgstr "" + +#: ../../tutorials/add-readme.md:75 +msgid "" +"Whether your package has been reviewed and vetted by an organization such" +" as pyOpenSci and/or JOSS." +msgstr "" + +#: ../../tutorials/add-readme.md:77 +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:79 +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:81 +msgid "Step 3: Add a description of what your package does" +msgstr "" + +#: ../../tutorials/add-readme.md:83 +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:87 +msgid "Keep this section short." +msgstr "" + +#: ../../tutorials/add-readme.md:88 +msgid "Try to avoid jargon." +msgstr "" + +#: ../../tutorials/add-readme.md:89 +msgid "" +"Define technical terms that you use to make the description accessible to" +" more people." +msgstr "" + +#: ../../tutorials/add-readme.md:91 +msgid "" +"Remember that the more people understand what your package does, the more" +" people will use it." +msgstr "" + +#: ../../tutorials/add-readme.md:93 +msgid "Step 4: Add package installation instructions" +msgstr "" + +#: ../../tutorials/add-readme.md:95 +msgid "Next, add instructions that tell users how to install your package." +msgstr "" + +#: ../../tutorials/add-readme.md:97 +#, python-brace-format +msgid "" +"For example, can they use {term}`pip` to install your package? `python -m" +" pip install packagename`" +msgstr "" + +#: ../../tutorials/add-readme.md:100 +msgid "or conda?" +msgstr "" + +#: ../../tutorials/add-readme.md:102 +msgid "`conda install -c conda-forge packagename`." +msgstr "" + +#: ../../tutorials/add-readme.md:104 +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:108 +msgid "Step 5: Any additional setup" +msgstr "" + +#: ../../tutorials/add-readme.md:110 +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:115 +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:119 +msgid "authentication information, if it is applicable to your package." +msgstr "" + +#: ../../tutorials/add-readme.md:120 +msgid "additional tool installations, such as GDAL." +msgstr "" + +#: ../../tutorials/add-readme.md:123 +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:128 +msgid "Step 6: Add a get started section" +msgstr "" + +#: ../../tutorials/add-readme.md:130 +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:133 +msgid "Provide a fully functional code snippet if possible" +msgstr "" + +#: ../../tutorials/add-readme.md:136 +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:138 +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:140 +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:143 +msgid "For the pyosPackage, a short get started demo might look like this:" +msgstr "" + +#: ../../tutorials/add-readme.md:151 +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:154 +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:159 +msgid "Step 7: Community section" +msgstr "" + +#: ../../tutorials/add-readme.md:161 +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:163 +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 file in the " +"[next lesson](add-license-coc)." +msgstr "" + +#: ../../tutorials/add-readme.md:167 +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:170 +msgid "running tests" +msgstr "" + +#: ../../tutorials/add-readme.md:171 +msgid "making package releases" +msgstr "" + +#: ../../tutorials/add-readme.md:172 +msgid "building documentation" +msgstr "" + +#: ../../tutorials/add-readme.md:173 +msgid "and more." +msgstr "" + +#: ../../tutorials/add-readme.md:177 +msgid "Step 8: Citation information" +msgstr "" + +#: ../../tutorials/add-readme.md:179 +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:182 +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:186 +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:190 +msgid "The finished README file" +msgstr "" + +#: ../../tutorials/add-readme.md:192 +msgid "Your finished `README.md` file should look something like this:" +msgstr "" + +#: ../../tutorials/add-readme.md:242 +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:248 +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:252 +msgid "Builds trust with your users" +msgstr "" + +#: ../../tutorials/add-readme.md:253 +msgid "Discourages misuse of your package and associated code" +msgstr "" + +#: ../../tutorials/command-line-reference.md:6 ../../tutorials/intro.md:63 +msgid "Command Line Reference Guide" +msgstr "" + +#: ../../tutorials/command-line-reference.md:9 +msgid "" +"**What these tables are:** These tables summarize the command line inputs" +" (e.g., `pipx install hatch`, `hatch build` or `python -m build`) " +"necessary to complete all steps in the package creation process, from " +"installing [Hatch](get-to-know-hatch) to publishing the package on [PyPI" +"](publish-pypi) and conda-forge." +msgstr "" + +#: ../../tutorials/command-line-reference.md:14 +#, python-brace-format +msgid "" +"**What these tables are not:** These tables do not cover the manual or " +"non-automated steps (e.g., create a PyPI account, create a {term}`API " +"token`) you have to complete throughout the package creation process." +msgstr "" + +#: ../../tutorials/command-line-reference.md:18 +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:21 +msgid "Environment Setup" +msgstr "" + +#: ../../tutorials/command-line-reference.md:43 +msgid "Package Development" +msgstr "" + +#: ../../tutorials/command-line-reference.md:62 +msgid "Package Publishing" +msgstr "" + +#: ../../tutorials/command-line-reference.md:81 +msgid "Versions and Environments" +msgstr "" + +#: ../../tutorials/create-python-package.md:7 +msgid "Create a pure Python package" +msgstr "" + +#: ../../tutorials/create-python-package.md:9 +#: ../../tutorials/develop-python-package-hatch.md:9 +msgid "About this lesson" +msgstr "" + +#: ../../tutorials/create-python-package.md:13 +#, python-brace-format +msgid "" +"This lesson uses the pyOpenSci Python package copier template to create a" +" {term}`Python package` quickly. Your package will be installable both " +"locally and remotely from a website such as GitHub (or GitLab) into a " +"Python environment." +msgstr "" + +#: ../../tutorials/create-python-package.md:18 +#: ../../tutorials/setup-py-to-pyproject-toml.md:23 +msgid "In this lesson, you will learn:" +msgstr "" + +#: ../../tutorials/create-python-package.md:20 +msgid "" +"How to make your code installable into any Python environment, both " +"locally and from GitHub" +msgstr "" + +#: ../../tutorials/create-python-package.md:21 +msgid "" +"How to update a [pyproject.toml file](pyproject-toml), which contains the" +" metadata needed to build, install, and publish your package." +msgstr "" + +#: ../../tutorials/create-python-package.md:23 +#, python-brace-format +msgid "" +"How to declare a {term}`Build backend` which will be used to [build" +"](build-package) and install your package" +msgstr "" + +#: ../../tutorials/create-python-package.md:25 +msgid "How to install your package in editable mode for interactive development" +msgstr "" + +#: ../../tutorials/create-python-package.md:28 +msgid "**What you need to complete this lesson**" +msgstr "" + +#: ../../tutorials/create-python-package.md:30 +msgid "" +"To complete this lesson, you will need a local Python environment and " +"shell on your computer. You will need to have " +"[Copier](https://copier.readthedocs.io/en/stable/) and [Hatch installed" +"](get-to-know-hatch) to complete the lesson successfully." +msgstr "" + +#: ../../tutorials/create-python-package.md:35 +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 such as " +"[gitbash](https://gitforwindows.org/) for any Shell and git-related " +"steps." +msgstr "" + +#: ../../tutorials/create-python-package.md:41 +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/create-python-package.md:43 +msgid "" +"In a [previous lesson, you learned what a Python package is](intro). " +"Creating a Python package allows you to install your code into any Python" +" environment on your computer. You can then import it into workflows in " +"the same way that you might import a package such as Pandas or GeoPandas." +" If you push your code to GitHub or GitLab, you can also install it " +"directly from there. [Scroll to the bottom of the page to learn more " +"about the basic elements of a Python package.](package-overview)." +msgstr "" + +#: ../../tutorials/create-python-package.md:49 +msgid "Create your Python package" +msgstr "" + +#: ../../tutorials/create-python-package.md:51 +msgid "" +"Below, you will create a pure Python package using the [pyOpenSci copier " +"template](https://github.com/pyOpenSci/pyos-package-template). Our " +"template uses Hatch as the default packaging tool. At the bottom of this " +"lesson, you'll learn more about the basics of the Python package " +"directory structure, and associated key files (`__init__.py` and " +"`pyproject.toml`)." +msgstr "" + +#: ../../tutorials/create-python-package.md:53 +msgid "Step 1: Set Up the Package Directory Structure" +msgstr "" + +#: ../../tutorials/create-python-package.md:55 +msgid "Open your shell or preferred terminal." +msgstr "" + +#: ../../tutorials/create-python-package.md:56 +msgid "" +"Use the shell `cd` command to navigate in your shell to the location " +"where you'd like your package to live. Our template will create the " +"package directory structure for you" +msgstr "" + +#: ../../tutorials/create-python-package.md:57 +msgid "Choose a name for your package. The name should:" +msgstr "" + +#: ../../tutorials/create-python-package.md:58 +msgid "Have no spaces (*Required*)" +msgstr "" + +#: ../../tutorials/create-python-package.md:59 +msgid "" +"Use all lowercase characters (*Recommended*). For this tutorial, we will " +"use `pyospackage`." +msgstr "" + +#: ../../tutorials/create-python-package.md:60 +msgid "" +"Only use letters 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` are both OK." +msgstr "" + +#: ../../tutorials/create-python-package.md:62 +msgid "" +"In your terminal, **run the command below**. This will begin a series of " +"prompts that will ask you questions and help you to customize your Python" +" package." +msgstr "" + +#: ../../tutorials/create-python-package.md:68 +msgid "" +"After running the command above, the template will walk you through a " +"series of questions." +msgstr "" + +#: ../../tutorials/create-python-package.md:70 +msgid "" +"Note that when you reach the prompt \"Do you want to answer one more " +"question, and skip the rest, using the default values?\" you can choose " +"Yes, but with a minimal setup to create the most basic version" +" of your package that contains documentation, tests and a example module " +"for you to use." +msgstr "" + +#: ../../tutorials/create-python-package.md:72 +msgid "" +"After this question, the template will ask you for your preferred GitHub " +"username and will then create a package with basic tests, documentation, " +"and GitHub configuration setup for you." +msgstr "" + +#: ../../tutorials/create-python-package.md:93 +msgid "" +"The template will then begin to copy files into the directory that used " +"above. (`.` means current working directory.)" +msgstr "" + +#: ../../tutorials/create-python-package.md:101 +msgid "The final package structure will look like this:" +msgstr "" + +#: ../../tutorials/create-python-package.md +msgid "A full package with tests, docs, and GitHub infrastructure" +msgstr "" + +#: ../../tutorials/create-python-package.md:119 +msgid "" +"If you use the \"bells and whistles\" default option when working through" +" the template prompts, our template will create a complete package setup " +"with GitHub CI actions, typing, tests, environments, and more using " +"Hatch. If you customize the entire package, then you can select what " +"platform you wish to host it on (GitHub vs GitLab), whether you want " +"typing, what documentation engine you want to use, and more." +msgstr "" + +#: ../../tutorials/create-python-package.md:123 +msgid "The resulting package directory looks like this:" +msgstr "" + +#: ../../tutorials/create-python-package.md:146 +msgid "The default tools that your package uses are:" +msgstr "" + +#: ../../tutorials/create-python-package.md:148 +msgid "" +"[Sphinx](https://www.pyopensci.org/python-package-guide/documentation" +"/hosting-tools/sphinx-python-package-documentation-tools.html) with the " +"PyData Sphinx Theme for documentation" +msgstr "" + +#: ../../tutorials/create-python-package.md:149 +msgid "pytest for testing" +msgstr "" + +#: ../../tutorials/create-python-package.md:150 +msgid "Hatch for environment setup" +msgstr "" + +#: ../../tutorials/create-python-package.md:152 +msgid "" +"**Full customization** If you want to customize any elements of your " +"package setup, choose `No, I want to fully customize the template.`. " +"This will allow you to select:" +msgstr "" + +#: ../../tutorials/create-python-package.md:155 +msgid "Sphinx vs [MkDocs](https://www.mkdocs.org/) vs no documentation" +msgstr "" + +#: ../../tutorials/create-python-package.md:156 +msgid "GitHub vs GitLab" +msgstr "" + +#: ../../tutorials/create-python-package.md:157 +msgid "VCS versioning" +msgstr "" + +#: ../../tutorials/create-python-package.md:158 +msgid "and more" +msgstr "" + +#: ../../tutorials/create-python-package.md:161 +msgid "Step 2: Explore the existing module in your package" +msgstr "" + +#: ../../tutorials/create-python-package.md:163 +#, python-brace-format +msgid "" +"A {term}`Module` refers to a `.py` file containing the code that you want" +" your package to access and run. Within the `pyospackage` subdirectory, " +"you have an `example.py` module that you can use to test out your package" +" quickly." +msgstr "" + +#: ../../tutorials/create-python-package.md:167 +msgid "Notice that the code in the example.py module, has a few features:" +msgstr "" + +#: ../../tutorials/create-python-package.md:169 +msgid "It has a [numpy-style docstring](numpy-docstring)" +msgstr "" + +#: ../../tutorials/create-python-package.md:170 +msgid "It uses [typing](type-hints)" +msgstr "" + +#: ../../tutorials/create-python-package.md:171 +msgid "" +"At the top of the module, there is a docstring explaining what the module" +" does." +msgstr "" + +#: ../../tutorials/create-python-package.md:173 +msgid "" +"Python supports different docstring formats. The most popular formats for" +" documenting Python objects are NumPy Style Docstring[^numpydoc], Google " +"Style Docstring[^googledoc], and the Epytext Style " +"Docstrings[^epytextdoc]." +msgstr "" + +#: ../../tutorials/create-python-package.md:175 +msgid "**pyOpenSci recommends using the NumPy Docstring convention.**" +msgstr "" + +#: ../../tutorials/create-python-package.md:177 +msgid "" +"[Learn more about docstrings here](api-docstrings) for an overview of " +"both topics." +msgstr "" + +#: ../../tutorials/create-python-package.md:206 +msgid "Python modules and the `__init__.py` file" +msgstr "" + +#: ../../tutorials/create-python-package.md:210 +msgid "The word module refers to a `.py` file containing Python code." +msgstr "" + +#: ../../tutorials/create-python-package.md:212 +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/create-python-package.md:217 +msgid "Step 3: Optional -- Add code to your module" +msgstr "" + +#: ../../tutorials/create-python-package.md:219 +msgid "" +"If you want, add a second function to the `example.py` module. It can be " +"a simple function. For example, write a second function that multiplies " +"numbers." +msgstr "" + +#: ../../tutorials/create-python-package.md:222 +msgid "Step 4: Check out the metadata in your `pyproject.toml` file" +msgstr "" + +#: ../../tutorials/create-python-package.md:224 +msgid "" +"A [pyproject.toml](pyproject-toml) file stores metadata that provides " +"instructions to various tools interacting with it, including [Hatch](get-" +"to-know-hatch), which will build your package. You can also specify " +"metadata for your package." +msgstr "" + +#: ../../tutorials/create-python-package.md:229 +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/create-python-package.md:232 +msgid "" +"The metadata in your generated `pyproject.toml` is already setup for you " +"using the information you provided the copier template above." +msgstr "" + +#: ../../tutorials/create-python-package.md:234 +msgid "Brief overview of the TOML file" +msgstr "" + +#: ../../tutorials/create-python-package.md:237 +msgid "" +"[The TOML format](https://toml.io/en/) consists of tables and variables. " +"Tables are sections of information denoted by square brackets:" +msgstr "" + +#: ../../tutorials/create-python-package.md:239 +msgid "`[this-is-a-table]`." +msgstr "" + +#: ../../tutorials/create-python-package.md:241 +msgid "" +"Tables can contain variables within them defined by a variable name and " +"an `=` sign. For instance, a `build-system` table most often holds two " +"(2) variables:" +msgstr "" + +#: ../../tutorials/create-python-package.md:244 +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/create-python-package.md:246 +msgid "" +"`build-backend = `, which is used to define the specific build-backend " +"name, (in this example we are using `hatchling.build`)." +msgstr "" + +#: ../../tutorials/create-python-package.md:255 +msgid "" +"TOML organizes data structures, defining relationships within a " +"configuration file." +msgstr "" + +#: ../../tutorials/create-python-package.md:258 +msgid "[Learn more about the pyproject.toml format here.](pyprojecttoml-metadata)" +msgstr "" + +#: ../../tutorials/create-python-package.md:261 +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/create-python-package.md:262 +msgid "" +"Make sure the package version, package name, and author name look " +"correct. The email is optional." +msgstr "" + +#: ../../tutorials/create-python-package.md:300 +msgid "" +"At the bottom of the template-generated `pyproject.toml` file, you will " +"see a section that defines Hatch environments. We will cover Hatch " +"environments in a later lesson." +msgstr "" + +#: ../../tutorials/create-python-package.md:302 +msgid "The bare minimum needed in a pyproject.toml file" +msgstr "" + +#: ../../tutorials/create-python-package.md:305 +msgid "" +"The core information that you need in a `pyproject.toml` file 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/create-python-package.md:307 +msgid "" +"Once you have your project metadata in the `pyproject.toml` file, you " +"will rarely update it." +msgstr "" + +#: ../../tutorials/create-python-package.md:311 +msgid "Step 5: Install your package locally" +msgstr "" + +#: ../../tutorials/create-python-package.md:313 +msgid "At this point, you should have:" +msgstr "" + +#: ../../tutorials/create-python-package.md:315 +msgid "A project directory structure with a `pyproject.toml` file at the root" +msgstr "" + +#: ../../tutorials/create-python-package.md:316 +msgid "A package directory containing an empty `__init__.py` file and" +msgstr "" + +#: ../../tutorials/create-python-package.md:317 +msgid "At least one Python module (e.g. `example.py`)" +msgstr "" + +#: ../../tutorials/create-python-package.md:319 +msgid "You are now ready to install (and build) your Python package!" +msgstr "" + +#: ../../tutorials/create-python-package.md:321 +msgid "" +"While you can do this using Hatch, we will use pip for this lesson, so " +"you can see how to install your tool into your preferred environment." +msgstr "" + +#: ../../tutorials/create-python-package.md:323 +msgid "" +"First, open your preferred shell (Windows users may use something like " +"GitBash) and `cd` into your project directory if you are not already " +"there." +msgstr "" + +#: ../../tutorials/create-python-package.md:324 +msgid "Activate the Python environment that you wish to use." +msgstr "" + +#: ../../tutorials/create-python-package.md:325 +msgid "Run `python -m pip install -e .`" +msgstr "" + +#: ../../tutorials/create-python-package.md:327 +#: ../../tutorials/create-python-package.md:560 +#: ../../tutorials/create-python-package.md:567 +#: ../../tutorials/get-to-know-hatch.md:199 ../../tutorials/intro.md:246 +#: ../../tutorials/publish-pypi.md:9 ../../tutorials/publish-pypi.md:185 +#: ../../tutorials/publish-pypi.md:358 ../../tutorials/pyproject-toml.md:744 +msgid "Todo" +msgstr "" + +#: ../../tutorials/create-python-package.md:328 +msgid "Add this back in when the lesson is published" +msgstr "" + +#: ../../tutorials/create-python-package.md:329 +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/create-python-package.md:355 +msgid "What does `python -m pip install -e .` do?" +msgstr "" + +#: ../../tutorials/create-python-package.md:358 +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 need to restart Python." +msgstr "" + +#: ../../tutorials/create-python-package.md:363 +msgid "" +"If you wish to install the package regularly (not in editable mode) you " +"can use:" +msgstr "" + +#: ../../tutorials/create-python-package.md:366 +msgid "`python -m pip install . `" +msgstr "" + +#: ../../tutorials/create-python-package.md:368 +msgid "**Using `python -m` when calling `pip`**" +msgstr "" + +#: ../../tutorials/create-python-package.md:370 +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/create-python-package.md:374 +msgid "" +"IMPORTANT: pip can also be used to install packages from PyPI. However, " +"in this case, you are telling pip to install your package from a local " +"folder by using the `.`. You could also specify a path to the project " +"directory on your computer instead of the `.` which tells pip to use the " +"current working directory." +msgstr "" + +#: ../../tutorials/create-python-package.md:377 +msgid "Look for pyospackage in your environment" +msgstr "" + +#: ../../tutorials/create-python-package.md:379 +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 return a" +" list of packages in the current active environment." +msgstr "" + +#: ../../tutorials/create-python-package.md:383 +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/create-python-package.md:411 +msgid "Step 6: Test out your new package" +msgstr "" + +#: ../../tutorials/create-python-package.md:413 +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/create-python-package.md:416 +msgid "You can now import your package and access the `add_numbers` function." +msgstr "" + +#: ../../tutorials/create-python-package.md:428 +msgid "Installing packages from GitHub" +msgstr "" + +#: ../../tutorials/create-python-package.md:430 +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/create-python-package.md:437 +msgid "To make your package GitHub installable, you can:" +msgstr "" + +#: ../../tutorials/create-python-package.md:439 +msgid "Create a new GitHub repository" +msgstr "" + +#: ../../tutorials/create-python-package.md:440 +msgid "" +"Push the contents of the project directory that you created above, to " +"GitHub" +msgstr "" + +#: ../../tutorials/create-python-package.md:441 +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/create-python-package.md:443 +msgid "" +"For instance below you install the pyospackage from the main branch of " +"the pyOpenSci repository." +msgstr "" + +#: ../../tutorials/create-python-package.md:446 +msgid "`python -m pip install git+https://github.com/user/repo.git@branch_or_tag`" +msgstr "" + +#: ../../tutorials/create-python-package.md:450 +msgid "Congratulations! You created your first Python package" +msgstr "" + +#: ../../tutorials/create-python-package.md:452 +msgid "" +"You have now created a Python package that you can install into any " +"Python environment." +msgstr "" + +#: ../../tutorials/create-python-package.md:457 +msgid "" +"Add a [README file](add-readme.md) and [LICENSE](add-license-coc.md) to " +"your package" +msgstr "" + +#: ../../tutorials/create-python-package.md:458 +msgid "" +"[Add more metadata to your `pyproject.toml`](pyproject-toml.md) file to " +"support PyPI publication." +msgstr "" + +#: ../../tutorials/create-python-package.md:459 +msgid "" +"[Learn how to build your package distribution](publish-pypi) files " +"(**sdist** and **wheel**) and publish to **test PyPI**." +msgstr "" + +#: ../../tutorials/create-python-package.md:460 +msgid "" +"Finally you will learn how to [publish to **conda-forge**](publish-conda-" +"forge) from **PyPI**." +msgstr "" + +#: ../../tutorials/create-python-package.md:464 +msgid "About the Python package directory structure" +msgstr "" + +#: ../../tutorials/create-python-package.md:466 +msgid "" +"To make your Python code installable you need to create a specific " +"directory structure with the following elements:" +msgstr "" + +#: ../../tutorials/create-python-package.md:468 +msgid "A `pyproject.toml` file." +msgstr "" + +#: ../../tutorials/create-python-package.md:469 +msgid "A specific directory structure." +msgstr "" + +#: ../../tutorials/create-python-package.md:470 +msgid "Some code." +msgstr "" + +#: ../../tutorials/create-python-package.md:471 +msgid "An `__init__.py` file in your code directory." +msgstr "" + +#: ../../tutorials/create-python-package.md:473 +msgid "The directory structure you'll create in this lesson will look like this:" +msgstr "" + +#: ../../tutorials/create-python-package.md:488 +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/create-python-package.md:490 +msgid "" +"Once you have the basic items of a Python package (code, metadata and a " +"file structure), you can `pip install` your package into any Python " +"environment on your computer." +msgstr "" + +#: ../../tutorials/create-python-package.md:493 +msgid "About the basic package directory structure" +msgstr "" + +#: ../../tutorials/create-python-package.md:495 +msgid "Notice a few things about the above layout:" +msgstr "" + +#: ../../tutorials/create-python-package.md:497 +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/create-python-package.md:498 +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/create-python-package.md:499 +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/create-python-package.md:500 +msgid "The `pyproject.toml` file lives at the root directory of your package." +msgstr "" + +#: ../../tutorials/create-python-package.md:501 +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/create-python-package.md:503 +msgid "What is an `__init__.py` file?" +msgstr "" + +#: ../../tutorials/create-python-package.md:505 +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/create-python-package.md:509 +msgid "" +"For example, following the file structure example above which has an " +"`__init__.py` file within it, you can run:" +msgstr "" + +#: ../../tutorials/create-python-package.md:515 +#: ../../tutorials/pyproject-toml.md:56 +msgid "What is a pyproject.toml file?" +msgstr "" + +#: ../../tutorials/create-python-package.md:517 +msgid "The **pyproject.toml** file is:" +msgstr "" + +#: ../../tutorials/create-python-package.md:519 +msgid "" +"Where you define your project's metadata (including its name, authors, " +"license, etc)" +msgstr "" + +#: ../../tutorials/create-python-package.md:520 +msgid "Where you define dependencies (the packages that it depends on)" +msgstr "" + +#: ../../tutorials/create-python-package.md:521 +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/create-python-package.md:523 +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/create-python-package.md:529 +msgid "The `build-backend` that you want to use," +msgstr "" + +#: ../../tutorials/create-python-package.md:530 +msgid "The project `name` and `version`." +msgstr "" + +#: ../../tutorials/create-python-package.md:532 +msgid "Why the pyproject.toml file is important" +msgstr "" + +#: ../../tutorials/create-python-package.md:535 +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/create-python-package.md:545 +msgid "" +"If your project already has a `setup.py` file, Hatch can be used to " +"automatically create a `pyproject.toml`." +msgstr "" + +#: ../../tutorials/create-python-package.md:546 +msgid "" +"See [Using Hatch to Migrate setup.py to a pyproject.toml](setup-py-to-" +"pyproject-toml.md)" +msgstr "" + +#: ../../tutorials/create-python-package.md:561 +msgid "" +"Is it clear where to add commands? Bash vs. Python console Bash vs. Zsh " +"is different" +msgstr "" + +#: ../../tutorials/create-python-package.md:563 +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/create-python-package.md:564 +msgid "They can use a codespace to complete this lesson too." +msgstr "" + +#: ../../tutorials/create-python-package.md:568 +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/create-python-package.md:552 +msgid "[Carpentries shell lesson](https://swcarpentry.github.io/shell-novice/)" +msgstr "" + +#: ../../tutorials/create-python-package.md:556 +msgid "[Numpy style docs](https://numpydoc.readthedocs.io/en/latest/format.html)" +msgstr "" + +#: ../../tutorials/create-python-package.md:555 +msgid "[Google docstring style](https://google.github.io/styleguide/pyguide.html)" +msgstr "" + +#: ../../tutorials/create-python-package.md:557 +msgid "[epydoc](https://epydoc.sourceforge.net/epytext.html)" +msgstr "" + +#: ../../tutorials/create-python-package.md:554 +msgid "" +"[Python module " +"docs](https://docs.python.org/3/tutorial/modules.html#packages)" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:7 +msgid "Use Hatch environments with your pure Python package" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:13 +msgid "" +"[In a previous lesson](create-pure-python-package), you learned how to " +"create a Python package using the pyOpenSci copier template. In this " +"lesson, you'll learn how to manage and use the Hatch environments set up " +"by de **What you need to complete this lesson**" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:16 +msgid "" +"To complete this lesson, you will need a local Python environment and " +"shell on your computer. You will need to have created a package using " +"our pyOpenSci copier template. You should also have [Hatch installed" +"](get-to-know-hatch)." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:20 +msgid "" +"If you are using Windows or are not familiar with Shell, you may want to " +"check out the [Carpentries shell lesson](https://swcarpentry.github.io" +"/shell-novice/). Windows users will likely need to configure a tool such " +"as [GitBash](https://gitforwindows.org/) for any Shell and git-related " +"steps." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:23 +msgid "" +"Welcome to your shiny new package! This page will help you get started " +"with using [Hatch](get-to-know-hatch) to run tests, build and check your " +"package, and build your documentation." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:27 +#, python-brace-format +msgid "" +"To begin, have a look at the [pyproject.toml](pyproject-toml) file in " +"your package directory. This file contains the configuration for your " +"package and is written using {term}`TOML` format. Here's the TL&DR:" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:31 +msgid "Each `[]` section in the toml file is called a table." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:32 +msgid "You can nest tables with double brackets like this`[[]]`" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:33 +msgid "" +"Tables contain information about a certain thing that you want to " +"configure." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:36 +msgid "" +"You can configure Hatch to use UV by default for environment management. " +"UV is a package manager built in Rust. It is fast and will significantly " +"speed up environment creation." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:38 +msgid "" +"To use UV with Hatch, configure Hatch in the \"tools\" section of your " +"`pyproject.toml` file." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:46 +msgid "" +"Using Hatch for developing, building, and maintaining your pure Python " +"package" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:48 +#, python-brace-format +msgid "" +"In the pyOpenSci Python package template, we have set up {term}`Hatch " +"environment` definitions. You will notice at the bottom of the file, a " +"[hatch environment](https://hatch.pypa.io/1.13/environment/) section, " +"that looks like this:" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:59 +msgid "" +"Hatch allows you to configure and run environments and scripts similar to" +" a workflow tool like tox or nox." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:62 +msgid "" +"Hatch defaults to using `venv` to manage environments. However, you can " +"configure it to use other environment tools, such as conda or mamba." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:64 +msgid "" +"[Read the hatch documentation to learn more about environments. " +"](https://hatch.pypa.io/1.13/tutorials/environment/basic-usage/)" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:68 +msgid "" +"Below is the Hatch environment used to build and test your package. " +"Anytime you see: `tool.hatch.envs.test`, it tells Hatch:" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:71 +msgid "" +"\"Hey, Hatch, this is the definition for an environment.`test` is the " +"name of the environment that I want you to create.\"" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:73 +msgid "So `tool.hatch.envs.build` will create an environment called `build`." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:75 +msgid "" +"Below the environment \"declaration,\" you can see the definition of what" +" should be in that environment." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:77 +msgid "A Hatch environment to build your package" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:79 +#, python-brace-format +msgid "" +"Below is a Hatch environment definition that you will find in your new " +"project's [pyproject.toml](pyproject-toml) file. It is set up to build " +"your package's {term}`Distribution files` ({term}`Source distribution " +"(sdist)` and {term}`Wheel (.whl)`)." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:84 +#, python-brace-format +msgid "" +"Notice that the environment definition declares two {term}`Dependencies`:" +" `pip` and `twine`, which the environment needs to run successfully. This" +" declaration is similar to declaring dependencies for your package at the" +" top of your [pyproject.toml](pyproject-toml)." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:99 +msgid "Hatch will install your package in editable mode by default" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:100 +msgid "" +"Notice the `detached = True` flag at the bottom of the environment. By " +"default, hatch will install your package in editable mode into any " +"environment it creates. `detached=True` tells it not to install your " +"package into the environment." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:104 +msgid "Hatch scripts" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:106 +#, python-brace-format +msgid "" +"Hatch supports defining {term}`Script (Hatch)` commands that run in " +"specific Hatch environments." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:109 +msgid "" +"Above, you have defined a new environment called 'build' that Hatch will " +"create as a virtual environment (venv). Because `detached = True` in that" +" environment, Hatch won't install your package into it." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:111 +msgid "" +"You can then use that environment to run \"scripts\". The definition " +"below tells Hatch to run the following scripts in the build environment." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:113 +msgid "`[tool.hatch.envs.build.scripts]`" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:115 +msgid "You define this `scripts` to run using the following syntax, where:" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:117 +msgid "`tool.hatch`: Alerts Hatch that this table is for Hatch to use" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:118 +msgid "`envs.build`: Use the defined build environment." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:119 +msgid "" +"`scripts`: Define what scripts to run. In this case, Hatch will run shell" +" scripts." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:122 +msgid "" +"Below is the `build.scripts` table that defines 3 shell commands to be " +"run:" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:124 +msgid "`pip check` # verifies your dependencies" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:125 +msgid "`hatch build --clean` # build your packages distribution files." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:126 +msgid "" +"`twine check dist/*` # use twine to check that your package's sdist " +"(source distribution) is ok." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:140 +msgid "" +"Hatch, by default, will install your package in editable mode into any " +"virtual environment (venv) that it creates. If `detached=True` is set, " +"then it will skip that step." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:143 +msgid "Running the build script" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:145 +msgid "You can run the build script and build your package like this:" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:147 +msgid "`hatch run build:check`" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:149 +msgid "" +"This step updates the build environment and then builds and checks the " +"output distributions of your package." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:151 +msgid "You can enter the build environment in your shell to check it out:" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:157 +msgid "If you run `pip list` in the environment, twine will be there:" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:163 +#: ../../tutorials/develop-python-package-hatch.md:221 +msgid "To leave the environment use:" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:169 +msgid "Hatch, testing, and matrix environments" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:171 +msgid "" +"It's always helpful to run your tests on the Python versions that you " +"expect your users to be using. In this section, you'll explore the test " +"environment setup in the pyOpenSci template package." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:173 +msgid "Below, you see the Hatch environment test table." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:175 +msgid "" +"Similar to the above build environment, the environment below defines the" +" dependencies that Hatch needs to install into the test environment " +"(required to run your tests)." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:189 +msgid "Your test environment has a matrix associated with it" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:191 +msgid "" +"If the environment has a matrix associated with it, that tells Hatch to " +"run the tests across different Python versions. Below, you are running " +"tests on versions 3.10 through 3.13." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:194 +msgid "" +"Hatch by default will install Python [using " +"UV](https://docs.astral.sh/uv/guides/install-python/) both when you " +"install Hatch and also when you declare a matrix environment like the one" +" below" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:202 +msgid "" +"In your project, if you run `hatch shell test`, you will see the output " +"below. This means that because there is a matrix of Python versions to " +"choose from, you need to select the environment with the Python version " +"you want to use." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:215 +msgid "" +"Pick the Python test environment that you want to use and enter it, like " +"this (this will open Python 3.13):" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:227 +msgid "Hatch scripts for tests" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:229 +msgid "" +"In that same tests section, you will see a `tool.hatch.envs.test.scripts`" +" section. Similar to what you saw above with the build steps, this is " +"where the \"script\" to run your tests is defined." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:232 +msgid "" +"Notice that below, the script has a script called `run`. And that script " +"runs pytest with a set of arguments, including generating code coverage." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:239 +msgid "To run this script in your terminal, use the syntax:" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:241 +msgid "`hatch run test:run`" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:243 +msgid "Reminder" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:246 +msgid "" +"`hatch run`: this calls hatch and tells it that it will be running a " +"command" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:247 +msgid "" +"`test:run` defines the environment you want it to run (`test`) in this " +"case, and the script is defined as `run`" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:250 +msgid "" +"If you have a matrix setup for tests, then it will both install the " +"needed Python version using UV and run your tests in each version of the " +"Python environment. In this case, since there are four Python versions in" +" the environment, your tests will be run four times, once in each Python " +"version listed in the matrix table." +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:280 +msgid "Build your documentation with Hatch environments" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:282 +msgid "" +"Finally, you can build and serve your documentation using hatch. To build" +" a static HTML version of the docs run:" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:285 +msgid "`hatch run docs:build`" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:287 +msgid "" +"To run a local server with your docs updated as you update your markdown " +"files, run:" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:289 +msgid "`hatch run docs:serve`" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:291 +msgid "To stop serving the docs use:" +msgstr "" + +#: ../../tutorials/develop-python-package-hatch.md:293 +msgid "mac: ctrl + c windows:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:6 +msgid "Get to Know Hatch" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:8 +msgid "" +"Our Python packaging tutorials use Hatch. 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:13 +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:16 +#, python-brace-format +msgid "" +"It supports different {term}`Build backend` options if you ever need to " +"compile code in other languages." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:18 +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:21 +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:24 +msgid "You need two things to successfully complete this tutorial:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:26 +msgid "You need Python installed." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:27 +msgid "You need Hatch installed." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:30 +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:34 +msgid "Install Hatch" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:36 +msgid "" +"To begin, follow the operating-system-specific instructions below to " +"install Hatch." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md +msgid "MAC" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:43 +msgid "" +"Follow the instructions " +"[here](https://hatch.pypa.io/latest/install/#installers)." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:45 +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:46 +msgid "Run the installer and follow the setup instructions." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:47 +msgid "If your terminal is open, then restart it." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md +msgid "Windows" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:53 +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:55 +msgid "Run your downloaded installer file and follow the on-screen instructions." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md +msgid "Linux" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:61 +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:75 +#, python-brace-format +msgid "" +"Hatch can also be installed directly using {term}`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:80 +msgid "" +"Our Linux users have found success installing Hatch with pipx if they " +"already use apt install." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:83 +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:88 +msgid "Check that hatch installed correctly" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:90 +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:98 +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:101 +msgid "Configure Hatch" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:103 +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:107 +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:109 +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:113 +msgid "Step 1: Open and Edit Your `config.toml` File" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:115 +msgid "" +"To open the config file in your file browser, run the following command " +"in your shell:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:118 +msgid "`hatch config explore`" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:120 +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:123 +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:131 +msgid "Step 2 - update your email and name" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:133 +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](pyproject-toml) metadata files that you create using " +"Hatch." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:144 +msgid "Step 3" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:146 +msgid "Next, set tests to false in the `[template.plugins.default]` table." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:148 +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:153 +msgid "Your `config.toml` file should look something like the one below." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:191 +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://choosealicense.com/) and as such we will use" +" it for this tutorial series." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:197 +msgid "You are of course welcome to select another license." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:200 +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:203 +msgid "Step 4: Close the config file and run `hatch config show`" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:205 +msgid "" +"Once you have completed the steps above run the following command in your" +" shell." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:207 +msgid "`hatch config show`" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:209 +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:213 +msgid "Hatch features" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:215 +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:218 +msgid "Comparison to other tools" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:220 +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:223 +msgid "[More on Hatch here](hatch)" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:225 +msgid "A few features that Hatch offers" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:227 +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:229 +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:231 +msgid "Use `hatch -h` to see all of the available commands." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:233 +msgid "What's next" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:235 +msgid "" +"In the next lesson you'll learn how to package and make your code " +"installable using Hatch." +msgstr "" + +#: ../../tutorials/intro.md:34 ../../tutorials/setup-py-to-pyproject-toml.md:36 +msgid "Get to know Hatch" +msgstr "" + +#: ../../tutorials/intro.md:34 ../../tutorials/run-python-scripts-hatch.md:8 +msgid "Run standalone Python scripts with Hatch" +msgstr "" + +#: ../../tutorials/intro.md:34 +msgid "Python Packaging Tutorial Setup" +msgstr "" + +#: ../../tutorials/intro.md:42 ../../tutorials/intro.md:89 +msgid "What is a Python package?" +msgstr "" + +#: ../../tutorials/intro.md:42 +msgid "Create a Python package" +msgstr "" + +#: ../../tutorials/intro.md:42 +msgid "Publish to PyPI" +msgstr "" + +#: ../../tutorials/intro.md:42 +msgid "Publish to conda-forge" +msgstr "" + +#: ../../tutorials/intro.md:42 +msgid "Publish using GitHub Actions and Trusted Publishing" +msgstr "" + +#: ../../tutorials/intro.md:42 +msgid "Create and publish a Python Package" +msgstr "" + +#: ../../tutorials/intro.md:53 +msgid "Develop package (Hatch environments)" +msgstr "" + +#: ../../tutorials/intro.md:53 +msgid "Add README file" +msgstr "" + +#: ../../tutorials/intro.md:53 +msgid "Add a license & code of conduct" +msgstr "" + +#: ../../tutorials/intro.md:53 +msgid "Update metadata in pyproject.toml" +msgstr "" + +#: ../../tutorials/intro.md:53 +msgid "Project information files & metadata" +msgstr "" + +#: ../../tutorials/intro.md:63 +msgid "Reference Guides" +msgstr "" + +#: ../../tutorials/intro.md:70 +msgid "Migrate setup.py to a pyproject.toml using Hatch" +msgstr "" + +#: ../../tutorials/intro.md:70 +msgid "Hatch for Existing Packages" +msgstr "" + +#: ../../tutorials/intro.md:7 +msgid "Python packaging 101" +msgstr "" + +#: ../../tutorials/intro.md:9 +msgid "_A start to finish beginner-friendly tutorial_" +msgstr "" + +#: ../../tutorials/intro.md:11 +#, python-brace-format +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 " +"{term}`Python package`." +msgstr "" + +#: ../../tutorials/intro.md:17 +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:19 ../../tutorials/trusted-publishing.md:258 +msgid "" +"This lesson is the first in a series of lessons to help you get started " +"with Python packaging." +msgstr "" + +#: ../../tutorials/intro.md:22 +msgid "Who are these tutorials for?" +msgstr "" + +#: ../../tutorials/intro.md:24 +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:29 +msgid "" +"In this series you will learn about the core elements that you need to " +"publish your package to [PyPI](publish-pypi)." +msgstr "" + +#: ../../tutorials/intro.md:32 +msgid "" +"In the second series, you will learn about infrastructure and " +"documentation needed to support package maintenance." +msgstr "" + +#: ../../tutorials/intro.md:77 ../../tutorials/publish-conda-forge.md:22 +#: ../../tutorials/publish-pypi.md:20 ../../tutorials/pyproject-toml.md:27 +#: ../../tutorials/setup-py-to-pyproject-toml.md:20 +#: ../../tutorials/trusted-publishing.md:13 +msgid "Learning Objectives" +msgstr "" + +#: ../../tutorials/intro.md:79 +msgid "" +"This lesson introduces you to the basic components of a Python package. " +"After reading this lesson you will:" +msgstr "" + +#: ../../tutorials/intro.md:82 +msgid "Understand what a Python package is" +msgstr "" + +#: ../../tutorials/intro.md:83 +msgid "Be able to list the 5 core components of a Python package" +msgstr "" + +#: ../../tutorials/intro.md:84 +msgid "" +"Be able to explain the difference between generalizable code and code " +"that supports a specific scientific application" +msgstr "" + +#: ../../tutorials/intro.md:91 +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:94 +#, python-brace-format +msgid "" +"A Python package is basically a directory with a specific file structure." +" Within the package directory structure, there are {term}`Module` objects" +" 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:103 +msgid "" +"Diagram showing a sketch of a toolbox filled with different tools " +"including a hammer and a saw." +msgstr "" + +#: ../../tutorials/intro.md:105 +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:110 +msgid "Python packages are installable" +msgstr "" + +#: ../../tutorials/intro.md:112 +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:121 +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:126 +msgid "Why create a Python package?" +msgstr "" + +#: ../../tutorials/intro.md:128 +msgid "You might create a Python package because you want to:" +msgstr "" + +#: ../../tutorials/intro.md:130 +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:131 +#, python-brace-format +msgid "" +"**Share your code:** If you publish a package on a public repository such" +" as PyPI or conda-forge, your package can be installed on any machine " +"using {term}`pip` or conda with a single command." +msgstr "" + +#: ../../tutorials/intro.md:134 +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:135 +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:137 +msgid "What to consider before you create a package" +msgstr "" + +#: ../../tutorials/intro.md:139 +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:142 +msgid "Who you think will use your package" +msgstr "" + +#: ../../tutorials/intro.md:143 +msgid "How people might use your package and on what data (if data are relevant)" +msgstr "" + +#: ../../tutorials/intro.md:144 +msgid "Whether you have time to add things such as documentation and tests" +msgstr "" + +#: ../../tutorials/intro.md:145 +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:147 +msgid "" +"Before creating a user-facing package, it's important to consider all of " +"the above." +msgstr "" + +#: ../../tutorials/intro.md:149 +msgid "The elements of a Python package" +msgstr "" + +#: ../../tutorials/intro.md:153 ../../tutorials/intro.md:231 +msgid "Diagram showing .. more here if this stays." +msgstr "" + +#: ../../tutorials/intro.md:155 +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:161 +msgid "The core elements of Python package include:" +msgstr "" + +#: ../../tutorials/intro.md:163 +msgid "" +"**Code:** Functions and classes that provide functionality for a user of " +"your package" +msgstr "" + +#: ../../tutorials/intro.md:164 +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:165 +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:166 +msgid "" +"Development Documentation helps both maintainers and contributors " +"understand how to maintain a package's infrastructure." +msgstr "" + +#: ../../tutorials/intro.md:167 +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:168 +msgid "" +"**License:** An open source license, or license that is [OSI " +"approved](https://opensource.org/license/), 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:169 +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:171 +msgid "What pyOpenSci looks for in a package" +msgstr "" + +#: ../../tutorials/intro.md:174 +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:180 +msgid "Packages are more than just code - Infrastructure" +msgstr "" + +#: ../../tutorials/intro.md:182 +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:187 +msgid "Version control and storing your package on GitHub or GitLab" +msgstr "" + +#: ../../tutorials/intro.md:189 +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:194 +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:196 +msgid "GitHub & GitLab vs. Git" +msgstr "" + +#: ../../tutorials/intro.md:199 +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:204 +msgid "Issues or Ticket Trackers" +msgstr "" + +#: ../../tutorials/intro.md:206 +msgid "" +"GitHub and GitLab also both offer community features such as issues that " +"allow:" +msgstr "" + +#: ../../tutorials/intro.md:208 +msgid "you to communicate with your maintainers and contributor community" +msgstr "" + +#: ../../tutorials/intro.md:209 +msgid "users to report bugs, ask questions and request new features" +msgstr "" + +#: ../../tutorials/intro.md:210 +msgid "" +"you to publicly keep track of enhancements and features you want to work " +"on for your package." +msgstr "" + +#: ../../tutorials/intro.md:212 +msgid "Continuous integration and continuous deployment" +msgstr "" + +#: ../../tutorials/intro.md:214 +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:216 +msgid "**An example of Continuous integration:**" +msgstr "" + +#: ../../tutorials/intro.md:218 +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:220 +msgid "**An example of Continuous deployment:**" +msgstr "" + +#: ../../tutorials/intro.md:222 +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:224 +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:233 +msgid "The lifecycle of a scientific Python package." +msgstr "" + +#: ../../tutorials/intro.md:236 +msgid "When should you turn your code into a Python package?" +msgstr "" + +#: ../../tutorials/intro.md:238 +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:240 +msgid "There are a few use cases to consider:" +msgstr "" + +#: ../../tutorials/intro.md:242 +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:244 +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:247 +msgid "LINK to pip installable lesson when it's published - it's in review now" +msgstr "" + +#: ../../tutorials/intro.md:250 +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:253 +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:255 +msgid "Packages that you expect others to use should be well-scoped" +msgstr "" + +#: ../../tutorials/intro.md:257 +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:259 +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:261 +msgid "How does this relate to code for a research project?" +msgstr "" + +#: ../../tutorials/intro.md:264 +msgid "" +"A [Research Compendium](https://book.the-turing-way.org/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:269 +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:274 +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:275 +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:278 +msgid "Below are a few examples well scoped pyOpenSci packages:" +msgstr "" + +#: ../../tutorials/intro.md:280 +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:281 +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:283 +msgid "Matplotlib as an example" +msgstr "" + +#: ../../tutorials/intro.md:285 +msgid "" +"At the larger end of the user spectrum, Matplotlib is a great example. " +"Matplotlib does one thing really well:" +msgstr "" + +#: ../../tutorials/intro.md:288 +msgid "_It creates visual plots of data._" +msgstr "" + +#: ../../tutorials/intro.md:290 +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:296 +msgid "Code should also be clean & readable & documented" +msgstr "" + +#: ../../tutorials/intro.md:298 +msgid "" +"The code in your package should also be clean, readable, and well " +"documented." +msgstr "" + +#: ../../tutorials/intro.md:300 +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:304 +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:308 +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:312 +msgid "Making your package installable - publishing to PyPI & conda-forge" +msgstr "" + +#: ../../tutorials/intro.md:314 +msgid "Python packages and environments" +msgstr "" + +#: ../../tutorials/intro.md:316 +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:322 +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:324 +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:331 +msgid "Publishing a package to PyPI / Conda-Forge" +msgstr "" + +#: ../../tutorials/intro.md:333 +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:337 +msgid "" +"Learn [how to publish your package to PyPI in this tutorial.](publish-" +"pypi.md)" +msgstr "" + +#: ../../tutorials/intro.md:339 +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:341 +msgid "" +"[You will learn more about the conda-forge publication process here" +".](publish-conda-forge.md)" +msgstr "" + +#: ../../tutorials/intro.md:344 +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:346 +msgid "" +"In the image above, you can see the steps associated with publishing your" +" package on PyPI and conda-forge. PyPI supports [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:350 +msgid "Yay, your package has users! Now what?" +msgstr "" + +#: ../../tutorials/intro.md:352 +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:354 +msgid "To support your community, you'll want to add things like:" +msgstr "" + +#: ../../tutorials/intro.md:356 +msgid "" +"[a development guide that documents your maintainer workflow process " +"](/documentation/repository-files/development-guide.md)" +msgstr "" + +#: ../../tutorials/intro.md:357 +msgid "" +"[a code of conduct to defines community interaction standards and " +"expectations](/documentation/repository-files/code-of-conduct-file.md)" +msgstr "" + +#: ../../tutorials/intro.md:358 +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:360 +msgid "Support for contributors and maintainers" +msgstr "" + +#: ../../tutorials/intro.md:362 +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:364 +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:369 +msgid "What's next?" +msgstr "" + +#: ../../tutorials/intro.md:371 +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:373 +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:6 +msgid "Publish your Python package that is on PyPI to conda-forge" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:8 +msgid "In the previous lessons, you've learned:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:10 +msgid "" +"How to [create the most basic version of a Python package](create-python-" +"package.md). This entailed making your code installable." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:11 +msgid "[How to publish your Python package to PyPI](publish-pypi)" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:12 +msgid "How to add a `README` and `LICENSE` file to your package" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:13 +msgid "" +"How to setup your [pyproject.toml](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:17 +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:20 +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:26 ../../tutorials/publish-pypi.md:24 +msgid "In this lesson you will learn how to:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:28 +msgid "Create a conda-forge yaml recipe for your package using Grayskull" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:29 +msgid "" +"Submit the recipe (yaml file) to the conda-forge staged recipes " +"repository as a pull request" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:30 +msgid "" +"Maintain your conda-forge package by creating new releases for your " +"package on PyPI" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:33 +#, python-brace-format +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 {term}`Source distribution (sdist)` file." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:41 +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:43 +#, python-brace-format +msgid "" +"Once you have published both package distributions (the {term}`Source " +"distribution (sdist)` and the {term}`Wheel (.whl)`) 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:50 +msgid "What is conda-forge?" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:52 +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:55 +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:58 +msgid "[Learn more about conda channels here.](#about-conda)" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:62 +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:64 +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:67 +msgid "Why publish to conda-forge" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:69 +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:71 +msgid "How publishing to conda-forge works" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:73 +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:75 +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:77 +msgid "Conda-forge publication steps" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:80 +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:82 +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:85 +msgid "The steps to publish to conda-forge are:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:87 +msgid "Publish your Python package distribution files (sdist & wheel) to PyPI" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:88 +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:89 +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:91 +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:93 +msgid "" +"Once your recipe is accepted and merged on conda-forge, users can install" +" your package using:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:95 +msgid "`conda install -c conda-forge your-package`" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:97 +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:99 +msgid "Maintaining a conda-forge package" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:101 +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:103 +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:105 +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:107 +msgid "" +" How to Publish your package" +" on conda-forge" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:109 +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:112 +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:115 +msgid "" +"Only submit your package to conda-forge if you intend to maintain it over" +" time." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:118 +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:120 +msgid "Step 1: Install grayskull" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:122 +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:128 +msgid "or conda" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:134 +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:139 +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:142 +msgid "Step 2: Fork and clone the conda-forge staged-recipes repository" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:144 +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:145 +msgid "" +"fork and clone the [conda-forge/staged-recipes GitHub " +"repository](https://github.com/conda-forge/staged-recipes)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:146 +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:148 +msgid "`git checkout -b your-package-name `" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:150 +msgid "In bash, `cd` into the `staged-recipes/recipes` folder" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:158 +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:169 +msgid "Step 3: Create your conda-forge recipe" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:171 +msgid "Next, navigate to the recipes directory" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:173 +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:185 +msgid "Next, run `grayskull pypi your-package-name` to generate a recipe." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:229 +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:230 +msgid "" +"An internet connection is needed to run the `grayskull pypi your-package-" +"name` step." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:233 +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:235 +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:237 +msgid "`recipes/packagename/meta.yaml`" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:239 +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:242 +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:289 +msgid "Step 3b: Bug fix - add a home url to the about: section" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:291 +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:305 +msgid "to fix this, open your meta.yaml file in your favorite text editor." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:306 +msgid "and add a home: element to the about section" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:308 +msgid "The about section will look like this after you create your recipe." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:318 +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:329 +msgid "Step 4: tests for conda-forge" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:331 +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:333 +msgid "" +"`pip check` will ensure that your package installs properly with all of " +"the proper dependencies." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:345 +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:347 +msgid "Step 4: Submit a pull request to the staged-recipes repository" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:349 +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:351 +msgid "" +"Submit a pull request from your fork/branch of the staged-recipes " +"repository." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:352 +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 +msgid "Conda-forge checklist help" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:358 +msgid "Conda-forge Staged-recipes Pull Request Checklist" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:360 +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:362 +msgid "Below we break down each element of that list." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:364 +msgid "Pull request template checklist tips" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:367 +msgid "" +"-[x] Title of this PR is meaningful: e.g. \"Adding my_nifty_package\", " +"not \"updated meta.yaml\"." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:369 +msgid "" +"**Translation:** Make sure that your pull request title is specific. We " +"suggest something like: `Add recipe for `" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:372 +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:374 +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:376 +msgid "[x] Source is from official source." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:378 +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:380 +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:382 +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:384 +msgid "" +"-[x] If static libraries are linked in, the license of the static library" +" is packaged." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:386 +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:388 +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:390 +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:392 +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:397 +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:400 +msgid "-[ ] Build number is 0." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:402 +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:415 +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:417 +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:423 +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:425 +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:427 +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:429 +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:431 +msgid "" +"This is also why we don't suggest you publish to conda-forge as a " +"practice run." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:435 +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:439 +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:441 +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:444 +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:446 +msgid "Please be patient and wait for them to respond." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:448 +msgid "conda-forge staged recipes and CI failures" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:451 +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:453 +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:456 +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:458 +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:460 +msgid "" +" Congratulations - you " +"have added your package to conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:462 +msgid "" +"The last part of this process is maintaining the repository. We cover " +"that next." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:465 +msgid "Maintaining your conda-forge feedstock" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:467 +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:469 +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:471 +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:473 +msgid "`conda install -c conda-forge yourpackage`" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:477 +msgid "If you have walked through this entire tutorial series you will now:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:479 +msgid "Understand [what a Python package is ](intro.md)" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:480 +msgid "" +"Know how to [make your code installable](create-python-package.md) into " +"Python environments" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:481 +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:482 +msgid "Know how to [publish your package to PyPI](publish-pypi.md) and" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:483 +msgid "Know how to publish your package to conda-forge" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:485 +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:489 +msgid "[Grayskull blogpost](https://conda-forge.org/blog/2020/03/05/grayskull/)" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:490 +msgid "[Pipx documentation](https://pipx.pypa.io/stable/)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:7 +msgid "Publish your Python package to PyPI" +msgstr "" + +#: ../../tutorials/publish-pypi.md:11 +msgid "Make sure they add /dist to their .gitignore file. Where does that fit?" +msgstr "" + +#: ../../tutorials/publish-pypi.md:15 +msgid "In the previous Python packaging lessons, you've learned:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:17 +msgid "What a Python package is" +msgstr "" + +#: ../../tutorials/publish-pypi.md:18 +msgid "How to make your code installable." +msgstr "" + +#: ../../tutorials/publish-pypi.md:26 +#, python-brace-format +msgid "" +"Build your package's {term}`Source distribution (sdist)` and {term}`Wheel" +" (.whl)` {term}`Distribution files`" +msgstr "" + +#: ../../tutorials/publish-pypi.md:28 +msgid "Setup an account on TestPyPI (the process is similar for PyPI)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:29 +msgid "Publish your package to TestPyPI and PyPI" +msgstr "" + +#: ../../tutorials/publish-pypi.md:31 +msgid "" +"You will do all of your development work in this lesson using [Hatch" +"](get-to-know-hatch)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:34 +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:37 +msgid "" +"You will learn how to publish to conda-forge in the [next lesson" +"](publish-conda-forge)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:41 +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:43 +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:46 +msgid "TestPyPI vs PyPI" +msgstr "" + +#: ../../tutorials/publish-pypi.md:48 +msgid "" +"There are two repositories associated with PyPI to which you can upload " +"your Python package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:51 +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:52 +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:54 +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:57 +msgid "4 Steps for publishing a Python package on TestPyPI (or PyPI)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:59 +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:64 +msgid "**Create a package development environment**" +msgstr "" + +#: ../../tutorials/publish-pypi.md:65 +#, python-brace-format +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 use {term}`pip` to install your package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:66 +#, python-brace-format +msgid "" +"**Create an account on TestPyPI (or PyPI)**: You will need to create a " +"TestPyPI account and associated {term}`API 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:67 +msgid "**Publish to TestPyPI using `hatch publish`**" +msgstr "" + +#: ../../tutorials/publish-pypi.md:69 +msgid "" +"In a [future lesson](trusted-publishing), 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:71 +msgid "Learn more about building Python packages in our guide" +msgstr "" + +#: ../../tutorials/publish-pypi.md:75 +msgid "" +"[Learn more about what building a Python package is](../package-" +"structure-code/python-package-distribution-files-sdist-wheel)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:76 +msgid "" +"[Learn more about the package distribution file that PyPI needs called " +"the wheel](#python-wheel)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:77 +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:80 +msgid "Step 1: Create a Python package development environment" +msgstr "" + +#: ../../tutorials/publish-pypi.md:82 +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:84 +msgid "Use Hatch to create your environment." +msgstr "" + +#: ../../tutorials/publish-pypi.md:92 +msgid "Then view all of the current environments that hatch has access to:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:104 +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:114 +msgid "View what's in the environment using `pip list`:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:130 +msgid "At any time you can exit the environment using `exit`." +msgstr "" + +#: ../../tutorials/publish-pypi.md:144 +msgid "Hatch and environments" +msgstr "" + +#: ../../tutorials/publish-pypi.md:146 +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:149 +msgid "Hatch will:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:151 +msgid "Create a new virtualenv (venv) that is located on your computer." +msgstr "" + +#: ../../tutorials/publish-pypi.md:152 +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:154 +msgid "Step 2: Build your package's sdist and wheel distributions" +msgstr "" + +#: ../../tutorials/publish-pypi.md:156 +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:158 +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:159 +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:161 +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](create-python-" +"package)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:165 +msgid "To build your package run `hatch build`:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:176 +msgid "Learn more about building a Python package" +msgstr "" + +#: ../../tutorials/publish-pypi.md:178 +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:182 +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:186 +msgid "" +"➜ hatch build ────────────────────────────────────── sdist " +"────────────────────────────────────── dist/pyospackage-0.1.tar.gz " +"────────────────────────────────────── wheel " +"────────────────────────────────────── dist/pyospackage-0.1-py3-none-" +"any.whl" +msgstr "" + +#: ../../tutorials/publish-pypi.md:193 +msgid "" +" Congratulations - " +"you've created your Python package distribution files " +msgstr "" + +#: ../../tutorials/publish-pypi.md:195 +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:198 +msgid "Step 3. Setup your TestPyPI account" +msgstr "" + +#: ../../tutorials/publish-pypi.md:200 +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:204 +msgid "TestPyPI vs. PyPI" +msgstr "" + +#: ../../tutorials/publish-pypi.md:205 +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:208 +msgid "" +"[Open up a web browser and go to the TestPyPI " +"website](https://test.pypi.org/)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:209 +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:210 +msgid "Once you have an account setup, login to it." +msgstr "" + +#: ../../tutorials/publish-pypi.md:211 +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:213 +msgid "Example: `pyosPackage_yourNameHere`." +msgstr "" + +#: ../../tutorials/publish-pypi.md:215 +msgid "" +"How to rename your Python package if the name is already taken in (test) " +"PyPI" +msgstr "" + +#: ../../tutorials/publish-pypi.md:219 +msgid "Required" +msgstr "" + +#: ../../tutorials/publish-pypi.md:221 +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:222 +msgid "" +"Update the project name in your pyproject.toml file (e.g. `name = " +"\"pyospackage_yourNameHere\"`)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:223 +msgid "" +"Update the module folder name to be the same (e.g. " +"`src/pyospackage_yourNameHere`)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:224 +msgid "Rebuild your project (`hatch build`)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:225 +msgid "Publish your package to capture the name (continue this tutorial!)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:227 +msgid "Recommended" +msgstr "" + +#: ../../tutorials/publish-pypi.md:229 +msgid "Update the GitHub repository name to align with the new package name" +msgstr "" + +#: ../../tutorials/publish-pypi.md:230 +msgid "" +"Update your local project folder to match the new package name (e.g. " +"`pyospackage_yourNameHere/src`)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:231 +msgid "Update mentions of your repository name in other files (e.g. `README.md`)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:235 +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:237 +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:241 +msgid "Setup 2-factor (2FA) authentication" +msgstr "" + +#: ../../tutorials/publish-pypi.md:243 +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:246 +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:248 +msgid "" +"2-factor authentication is required for PyPI authentication as of 1 " +"January 2024." +msgstr "" + +#: ../../tutorials/publish-pypi.md:252 +msgid "Step 4. Create a package upload token" +msgstr "" + +#: ../../tutorials/publish-pypi.md:254 +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:256 +msgid "Why create package-specific tokens?" +msgstr "" + +#: ../../tutorials/publish-pypi.md:258 +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:261 +msgid "Follow the steps below to create your token" +msgstr "" + +#: ../../tutorials/publish-pypi.md:263 +msgid "Login to TestPyPI and go to your account settings" +msgstr "" + +#: ../../tutorials/publish-pypi.md:264 +msgid "Scroll down to the **API tokens** section" +msgstr "" + +#: ../../tutorials/publish-pypi.md:265 +msgid "Click on the **Add API Token** button" +msgstr "" + +#: ../../tutorials/publish-pypi.md:266 +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:267 +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:269 +msgid "Your token should look something like this:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:271 +msgid "`pypi-abunchofrandomcharactershere...`" +msgstr "" + +#: ../../tutorials/publish-pypi.md:273 +msgid "It should start with `pypi` followed by a dash and a bunch of characters." +msgstr "" + +#: ../../tutorials/publish-pypi.md:275 +msgid "Upload to TestPyPI using Hatch" +msgstr "" + +#: ../../tutorials/publish-pypi.md:277 +msgid "Once you have your token, you are ready to publish to TestPyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:280 +msgid "Run `hatch publish -r test`" +msgstr "" + +#: ../../tutorials/publish-pypi.md:282 +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:284 +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:285 +msgid "Paste your TestPyPI token value in at the `Enter your credentials` prompt:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:296 +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:300 +msgid "" +"Hatch also has a caching system so once you enter your credentials it " +"will remember them." +msgstr "" + +#: ../../tutorials/publish-pypi.md:303 +msgid "Install your package from TestPyPI" +msgstr "" + +#: ../../tutorials/publish-pypi.md:305 +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:310 +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:312 +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:315 +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:319 +msgid "`python -m pip install -i https://test.pypi.org/simple/ pyosPackage`" +msgstr "" + +#: ../../tutorials/publish-pypi.md:322 +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:326 +msgid "Time to install your package" +msgstr "" + +#: ../../tutorials/publish-pypi.md:328 +msgid "" +"On your computer, activate the development environment that you wish to " +"install your newly published package in." +msgstr "" + +#: ../../tutorials/publish-pypi.md:330 +msgid "Run the installation instructions for your package from TestPyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md +msgid "Conda" +msgstr "" + +#: ../../tutorials/publish-pypi.md +msgid "venv Mac / Linux" +msgstr "" + +#: ../../tutorials/publish-pypi.md:354 +msgid "The value of end-to-end tools like hatch, flit and poetry" +msgstr "" + +#: ../../tutorials/publish-pypi.md:355 +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:359 +msgid "" +"teach them to setup trusted publisher for actions... in the actions " +"lesson https://pypi.org/help/#twofa" +msgstr "" + +#: ../../tutorials/publish-pypi.md:362 +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:365 +msgid "Package-specific token vs trusted publisher" +msgstr "" + +#: ../../tutorials/publish-pypi.md:367 +msgid "" +"For long run maintenance of your package, you have two options related to" +" PyPI publication." +msgstr "" + +#: ../../tutorials/publish-pypi.md:370 +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:371 +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:373 +msgid "Trusted Publishing" +msgstr "" + +#: ../../tutorials/publish-pypi.md:376 +msgid "" +"While publishing from GitHub Action is possible using tokens, we " +"recommend the _Trusted Publishing_ approach as it also confers " +"significant security and usability benefits." +msgstr "" + +#: ../../tutorials/publish-pypi.md:378 +msgid "" +"On the usability front, when Trusted Publishing is enabled, users no " +"longer need to manually create API tokens on PyPI and store them in the " +"GitHub release workflow." +msgstr "" + +#: ../../tutorials/publish-pypi.md:380 +msgid "" +"On the security front, Trusted Publishing reduces a risk related to the " +"API token being long lived: with API tokens, as soon as an attacker gets " +"access to it, they can publish many packages and versions in your name " +"(depending on the scope of the token), until you discover the token " +"compromise and rotate the credential. Trusted Publishing avoids this " +"problem by minting very short lived tokens which expire automatically." +msgstr "" + +#: ../../tutorials/publish-pypi.md:382 +msgid "" +"For these benefits, it is recommended that users use _only_ the GitHub " +"Actions release workflow to publish packages." +msgstr "" + +#: ../../tutorials/publish-pypi.md:385 +msgid "" +"You will learn how to create the automated trusted publisher workflow in " +"a followup lesson." +msgstr "" + +#: ../../tutorials/publish-pypi.md:387 +msgid "OPTIONAL: If you want to use a manual token-based publication workflow" +msgstr "" + +#: ../../tutorials/publish-pypi.md:389 +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:392 +msgid "To do this:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:393 +msgid "Go to TestPyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:394 +msgid "Navigate to the \"Your Projects\" section of your account" +msgstr "" + +#: ../../tutorials/publish-pypi.md:395 +msgid "" +"Click on the manage button for the project that you wish to add a token " +"for" +msgstr "" + +#: ../../tutorials/publish-pypi.md:396 +msgid "Go to settings" +msgstr "" + +#: ../../tutorials/publish-pypi.md:397 +msgid "Click on \"Create a token for your-package-name-here\"" +msgstr "" + +#: ../../tutorials/publish-pypi.md:398 +msgid "" +"Create the token and follow the steps above publish your package using " +"the repository specific token." +msgstr "" + +#: ../../tutorials/publish-pypi.md:400 +msgid "And you're all done!" +msgstr "" + +#: ../../tutorials/publish-pypi.md:402 +msgid "Trusted Publishing instead of token-based publication" +msgstr "" + +#: ../../tutorials/publish-pypi.md:405 +msgid "" +"Trusted Publishing will generate short lived tokens, scoped to the " +"project, on demand, only when a specific release workflows gets " +"triggered. This solves all the security and usability issues associated " +"with storing credentials in files/GitHub secrets." +msgstr "" + +#: ../../tutorials/publish-pypi.md:411 +msgid "You have published your package to TestPyPI!" +msgstr "" + +#: ../../tutorials/publish-pypi.md:413 +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:415 +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:417 +msgid "You will learn how to do that in the next lesson." +msgstr "" + +#: ../../tutorials/publish-pypi.md:421 +msgid "https://docs.python.org/3/library/venv.html" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:6 +msgid "Make your Python package PyPI ready - pyproject.toml" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:8 +msgid "" +"In [the installable code lesson](create-python-package), 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)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:13 +msgid "Following that you learned how to add a:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:14 +msgid "[README.md](add-readme)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:15 +msgid "[LICENSE](add-license-coc) and" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:16 +msgid "[CODE_OF_CONDUCT](add-coc)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:18 +msgid "to the root of your project directory." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:20 +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:32 +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:33 +msgid "" +"How to declare information (metadata) about your project to help users " +"find and understand it on PyPI." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:35 +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 +msgid "Click for lesson takeaways" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:42 +msgid "When creating your pyproject.toml file, consider the following:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:44 +msgid "" +"There are only two required metadata tables that you need to install and " +"publish your Python package:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:45 +msgid "**[build-system]**" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:46 +msgid "**[project]**." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:47 +msgid "" +"The **[project]** table stores your package's metadata. Within the " +"**[project]** table, There are only two _required_ fields:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:48 +msgid "**name=**" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:49 +msgid "**version=**" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:50 +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:51 +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:52 +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:53 +msgid "" +"We suggest that you include your **[build-system]** table at the top of " +"your `pyproject.toml` file." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:58 +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:63 +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:67 +msgid "About the .toml format" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:69 +#, python-brace-format +msgid "" +"The **pyproject.toml** file is written in {term}`TOML` format. 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`." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:74 +msgid "" +"Below you can see the `[build-system]` table. Within that table there are" +" two required key/value pairs." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:77 +msgid "" +"`requires =` is the key and the value is `[\"hatchling\"]` within the " +"`[build-system]` array specified by square brackets `[]`." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:87 +msgid "What is the pyproject.toml used for?" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:89 +msgid "The pyproject.toml file tells your build tool:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:91 +#, python-brace-format +msgid "" +"What {term}`Build backend` to use to build your package (we are using " +"{term}`Hatchling` in this tutorial but there are [many others to choose " +"from](/package-structure-code/python-package-build-tools))." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:94 +msgid "How and where to retrieve your package's version:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:95 +msgid "**statically** where you declare the version `version = \"0.1.0\"` or" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:96 +msgid "" +"**dynamically** where the tool looks to the most recent tag in your " +"history to determine the current version." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:97 +#, python-brace-format +msgid "What {term}`Dependencies` your package needs" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:98 +msgid "What versions of Python your package supports (important for your users)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:100 +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:103 +msgid "How your package is built," +msgstr "" + +#: ../../tutorials/pyproject-toml.md:104 +msgid "What Python versions and operating systems it supports" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:105 +msgid "What it does," +msgstr "" + +#: ../../tutorials/pyproject-toml.md:106 +msgid "Who maintains it" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:108 +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:111 +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:113 +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:117 +msgid "How is pyproject.toml metadata used?" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:119 +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:122 +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:127 +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:133 +msgid "A more in-depth overview of pyproject.toml files" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:135 +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:138 +msgid "How to update your pyproject.toml file" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:140 +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:144 +msgid "" +"A `[build-system]` table where you defined your project's backend build " +"tool (`hatchling`)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:145 +msgid "A `[project]` table where you defined your project's version and name." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:147 +msgid "The `pyproject.toml` file that you created, looked like this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:159 +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:162 +msgid "drop a package dependency" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:163 +msgid "modify what Python versions your package supports." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:165 +msgid "More on hatchling" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:168 +msgid "" +"The documentation for the hatchling back-end is " +"[here](https://hatch.pypa.io/latest/config/metadata/)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:171 +msgid "Step 1: Add Author, maintainer and project description" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:173 +msgid "" +"After completing the [installable code tutorial](create-python-package), " +"you should have a pyproject.toml file with a project name and a version " +"in the `[project]` table." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:181 +msgid "Add the following to your table:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:183 +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:184 +msgid "package **authors**" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:185 +msgid "package **maintainers**" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:187 +msgid "The `description` is just a string like the other values you've set:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:198 +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:212 +msgid "Author names & emails" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:216 +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:225 +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:234 +msgid "don't have emails for everyone, we suggest that you only add names." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:237 +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 +msgid "" +"Learn More: What's the difference between author and maintainer in open " +"source?" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:265 +msgid "" +"When adding maintainers and authors, you may want to think about the " +"difference between the two." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:267 +msgid "Authors generally include people who:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:268 +msgid "originally created / designed developed the package and" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:269 +msgid "people who add new functionality to the package." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:271 +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:273 +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:275 +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:277 +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:281 +msgid "Step 2: Add README and license" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:283 +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 refer to the README from your pyproject.toml " +"file, and add a short code indicating your choice of LICENSE following " +"the example below." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:312 +msgid "" +"The license entry in your pyproject.toml file must use the [license " +"expression syntax](https://packaging.python.org/en/latest/specifications" +"/license-expression/). Often this is a short name (with no spaces) for " +"the license, such as \"MIT\", \"BSD-3-Clause\" or \"Apache-2.0\". More " +"precisely, it must be a valid SPDX license expression, as documented in " +"the [SPDX specification](https://spdx.github.io/spdx-spec/v2.2.2/SPDX-" +"license-expressions/), either version 2.2 or a later compatible version." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:314 +msgid "" +"If you have multiple licenses, or a custom license, you can also express " +"these using a license expression." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:316 +msgid "" +"If you want to distribute license files, or other files containing legal " +"information, with your package, you can include these using the " +"[`license-files`](https://packaging.python.org/en/latest/guides/writing-" +"pyproject-toml/#license-files) entry, but this is not required." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:318 +msgid "Step 3: Specify Python version with `requires-python`" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:320 +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:325 +msgid "But how do I figure out which Python versions I should support?" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:327 +msgid "" +"Good question. The Python developer guide provides a [status " +"page](https://devguide.python.org/versions/) (and a handy visualization) " +"that explains the status of each Python release. Python releases go " +"through several different phases that are explained in [PEP " +"602](https://peps.python.org/pep-0602/)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:329 +msgid "" +"We recommend that you use the latest Python release in the **bugfix** " +"phase. If your Python release is in the **security** phase, we recommend " +"migrating to a newer version of Python." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:331 +msgid "" +"[SPEC 0](https://scientific-python.org/specs/spec-0000/) of the " +"Scientific Python project suggests a common schedule for dependencies, " +"including Python release versions, and is also worth considering for your" +" project." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:360 +msgid "Step 4: Specify Dependencies" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:362 +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:370 +msgid "dependencies are added in an array (similar to a Python list) structure." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:376 +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:380 +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:382 +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:387 +msgid "Lower bounds look like this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:393 +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:404 +msgid "Your `pyproject.toml` file will now look like this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:434 +msgid "Pin dependencies with caution" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:435 +msgid "" +"\"Pinning\" a dependency means setting it to a specific version, like " +"this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:437 +msgid "`numpy == 1.0`." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:439 +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:447 +msgid "" +"Similarly, you should be cautious when specifying an upper bound on a " +"package. These two specifications are equivalent:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:455 +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:458 +msgid "Step 5: Add PyPI classifiers" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:460 +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:462 +msgid "What happens when you use incorrect classifiers?" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:465 +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:468 +msgid "Review that list and add items below to your `pyproject.toml` file:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:470 +msgid "development status" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:471 +msgid "intended audiences" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:472 +msgid "topic" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:473 +msgid "programming language support" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:475 +msgid "" +"The classifier key should look something like the example below. A few " +"notes:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:477 +msgid "" +"Your classifier values might be different depending upon your intended " +"audience, development status of your package and the Python versions that" +" you support" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:478 +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:517 +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:519 +msgid "Step 6: Add the `[project.urls]` table" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:521 +msgid "Finally, add the project.urls table to your pyproject.toml file." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:523 +msgid "" +"`project.urls` contains links that are relevant for your project. You " +"might want to include:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:525 +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:526 +msgid "" +"**Bug reports:** a link to your issues/discussions or wherever you want " +"users to report bugs." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:527 +msgid "**Source:** the GitHub / GitLab link for your project." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:572 +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:575 +msgid "Putting it all together - your completed pyproject.toml file" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:577 +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 +msgid "Appendix - Click for a fully commented pyproject.toml file" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:626 +msgid "" +"Below is a fully commented pyproject.toml file if you want to use it for " +"reference." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:692 +msgid "Example `pyproject.toml` files" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:694 +msgid "" +"Below are some examples of `pyproject.toml` files from various packages " +"in the scientific and pyOpenSci ecosystem." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:695 +msgid "" +"[PyPA's fully documented example pyproject.toml " +"file](https://github.com/pypa/sampleproject/blob/main/pyproject.toml)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:696 +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:702 +msgid "At this point you've created:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:704 +msgid "A [README.md](add-readme) file for your package" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:705 +msgid "A [CODE_OF_CONDUCT.md](add-coc) file to support your user community" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:706 +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:708 +msgid "" +"You also learned [how to publish your package to (test)PyPI](publish-" +"pypi)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:710 +msgid "Publish a new version of your package to PyPI" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:712 +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:714 +msgid "Try to republish now." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:716 +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:729 +msgid "Now use hatch to publish the new version of your package to test.PyPI.org." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:736 +msgid "Next (optional) step - publishing to conda-forge" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:738 +msgid "" +"You now have all of the skills that you need to publish your package to " +"PyPI." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:741 +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:745 +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:385 +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/run-python-scripts-hatch.md:10 +msgid "" +"Python supports inline metadata for scripts (a feature added in 2024). " +"This makes it possible to run standalone scripts with dependencies and " +"Python versions managed automatically." +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:14 +#, python-brace-format +msgid "" +"Many tools support this workflow, including PDM, [Hatch](get-to-know-" +"hatch), and {term}`uv`. In this tutorial, we focus on Hatch and UV. The " +"same metadata format can also be used with other tools." +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:22 +msgid "" +"[Hatch: How to run Python scripts](https://hatch.pypa.io/latest/how-" +"to/run/python-scripts/)" +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:23 +msgid "" +"[uv: Running " +"scripts](https://docs.astral.sh/uv/guides/scripts/#creating-a-python-" +"script)" +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:26 +msgid "How to create a reproducible script" +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:28 +#, python-brace-format +msgid "" +"Sometimes you want to share or run a single script without creating a " +"full {term}`Python package`. To do this, you can use inline script " +"metadata. This format lets you specify dependencies and Python versions " +"at the top of your script in a comment block." +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:34 +msgid "" +"When you add metadata at the top of a script, Hatch (or PDM or uv) will " +"use that metadata to:" +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:37 +msgid "Create an isolated virtual Python environment for that script." +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:38 +#, python-brace-format +msgid "" +"Install the {term}`Dependencies` listed in the script into that " +"environment." +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:39 +msgid "Use the required Python version that you specify in the metadata." +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:41 +msgid "" +"This approach is useful for workflows that you want to make reproducible," +" but that do not need to become full Python packages." +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:44 +msgid "Why use Hatch for scripts?" +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:46 +msgid "" +"Inline metadata helps you make scripts reproducible. Anyone can run your " +"script without manually creating a new environment or guessing which " +"dependencies it needs. Hatch takes care of installing dependencies and " +"using the correct Python version." +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:51 +msgid "How to add inline metadata to your script" +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:53 +msgid "" +"You will use Hatch in this example, but you can also use uv if that is " +"your preferred tool." +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:56 +#, python-brace-format +msgid "" +"First, create a new file named `script.py` with the block below at the " +"top. The metadata block starts with `# /// script` and ends with `# ///`." +" Everything in between must be {term}`TOML` metadata written as comments." +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:60 +msgid "" +"In the example below, the script requires Python 3.11 or newer, and NumPy" +" is declared as a dependency." +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:81 +msgid "Run the script with Hatch" +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:83 +msgid "" +"Open your terminal and change to the directory where `script.py` lives. " +"Then run:" +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:90 +msgid "" +"On first run, Hatch will create an environment and install dependencies. " +"On later runs, Hatch will reuse that environment so startup is faster." +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:94 +msgid "" +"The environment name is based on the script path. If you move the script " +"to a new location, Hatch will treat it as a new script environment." +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:98 +msgid "Optional: configure script environment behavior" +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:100 +msgid "" +"You can control script-specific Hatch behavior in the same metadata " +"block. For example, to use `pip` instead of `uv` as the installer:" +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:113 +msgid "Run the same script with uv" +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:115 +msgid "If you prefer uv, you can run the same inline-metadata script with:" +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:121 +msgid "" +"The same `# /// script` metadata block works with uv, including " +"`requires-python` and `dependencies`." +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:124 +msgid "" +"For more on using uv to run scripts, see the guide: [Running scripts with" +" uv](https://docs.astral.sh/uv/guides/scripts/#creating-a-python-script)." +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:128 +msgid "When to use scripts vs. packages" +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:130 +msgid "You may be wondering when to use scripts versus creating a package." +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:132 +msgid "This depends on your use case. Scripts are often useful when:" +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:134 +msgid "You have one small task, or a specific workflow that is not generalizable." +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:135 +msgid "" +"Your workflow is still evolving, but you want to run it in a reproducible" +" environment." +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:137 +msgid "You want reproducible dependencies quickly." +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:138 +msgid "You are sharing a single file with collaborators." +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:140 +msgid "Create a full package when:" +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:142 +msgid "You are building reusable modules for multiple projects." +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:143 +msgid "You need tests, documentation, releases, and long-term maintenance." +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:144 +msgid "Your codebase is growing beyond one or two scripts." +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:148 +msgid "[Get to know Hatch](get-to-know-hatch.md)" +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:149 +msgid "[Create a Python package](create-python-package.md)" +msgstr "" + +#: ../../tutorials/run-python-scripts-hatch.md:150 +msgid "[Command line reference guide](command-line-reference.md)" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:7 +msgid "Using Hatch to Migrate setup.py to a pyproject.toml" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:9 +msgid "" +"[Hatch](get-to-know-hatch) can be useful for generating your project's " +"[pyproject.toml](pyproject-toml) file if your project already has a " +"`setup.py` file." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:13 +msgid "Note" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:16 +msgid "" +"This step is not necessary and is only helpful if your project already " +"has a `setup.py` file defined." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:17 +msgid "" +"If your project does not already define a `setup.py` see [Make your " +"Python code installable](create-python-package)" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:25 +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:28 +msgid "What is Hatch?" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:30 +#, python-brace-format +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 {term}`Dependencies`, building distributions, and " +"publishing packages to repositories like [PyPI](publish-pypi)." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:40 +msgid "See [Get to know Hatch](get-to-know-hatch) for more information." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:43 +msgid "Prerequisites" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:45 +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:51 +msgid "Sample Directory Tree" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:53 +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:55 +msgid "Before `hatch init`" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:71 +msgid "After `hatch init`" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:89 +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:91 +msgid "Step-by-Step Guide" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:93 +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:95 +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:97 +msgid "" +"**Initialize Hatch**: Run the following command to initialize Hatch in " +"your project directory:" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:103 +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) for more information about the " +"`pyproject.toml`)." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:105 +msgid "" +"**Verify**: Verify that the `pyproject.toml` file accurately reflects " +"your project configuration and dependencies. You can manually edit the " +"file, but be cautious and ensure that the syntax is correct." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:107 +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:109 +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:115 +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:117 +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 "" + +#: ../../tutorials/trusted-publishing.md:6 +msgid "" +"Setup Trusted Publishing for secure and automated publishing via GitHub " +"Actions" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:8 +msgid "In the previous Python packaging lessons, you learned:" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:10 +msgid "[How to create a Python package](create-python-package)" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:11 +msgid "" +"How to publish the code to [PyPI](publish-pypi) and [Conda](publish-" +"conda-forge)" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:16 +msgid "In this lesson, you will learn how to:" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:18 +msgid "Automate building and publishing the package on GitHub Actions" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:19 +#, python-brace-format +msgid "Configure {term}`Trusted publishing` for the project" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:20 +msgid "" +"Secure your workflow using GitHub action hashes and versions in your " +"workflow file" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:22 +msgid "" +"This tutorial assumes that your project is hosted on GitHub and that you " +"want to publish a package from your project to PyPI." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:26 +msgid "Configure a release job on GitHub Actions" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:28 +msgid "" +"GitHub Actions[^gha] is an infrastructure provided by GitHub to automate " +"software workflows, straight from the GitHub repository of the project. " +"You can configure automated testing for every pull request, automate " +"publishing of documentation, automate creation of web pages for the " +"project, and even automate the release process. For this lesson, we will " +"focus on using actions to release and publish your Python package " +"securely to [PyPI](publish-pypi)." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:36 +msgid "Why Trusted Publishing Matters" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:38 +msgid "" +"If you are wondering why trusted publishing is so important, [check out " +"this blog post:](https://www.pyopensci.org/blog/python-packaging-" +"security-publish-pypi.html) that dives deeper into what can happen when " +"you don't lock down your publishing workflows." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:41 +msgid "Step 0: Create a release workflow" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:43 +msgid "" +"To get started, create a file named `release.yaml` under the " +"`.github/workflows` directory of your project. If the `.github/workflows`" +" directory does not exist, you can create it. It is GitHub's convention " +"that all GitHub Actions are configured via YAML files in the " +"`.github/workflows` directory." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:48 +msgid "Naming your workflow file" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:51 +msgid "" +"You can name the workflow file whatever you wish. We suggest using " +"something simple and expressive like `release.yaml` so you, your future " +"self, and contributors who work on your project know exactly what the " +"workflow does." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:56 +msgid "Step 1: Name the workflow" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:58 +msgid "At the top of the `release.yaml` file, type the following:" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:64 +msgid "" +"This provides a name to the workflow that you can use to quickly find all" +" runs of this GitHub Action on the \"Actions\" tab in the GitHub " +"repository." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:68 +msgid "" +"Graphic showing an example of a configured workflow for the release. On " +"the top, in the red box labeled \"1\" you see the \"Actions\" tab of the " +"GitHub repository. On the left, in the red box labeled \"2\" you can see " +"the name of the workflow, \"Release,\" as configured in this step. " +"Finally, in the center, in the red box labeled \"3\" you can see several " +"runs of the workflow, for the \"1.0\" and \"1.0.1\" releases of the " +"package." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:70 +msgid "" +"This image shows an example of a configured workflow for the release. On " +"the top, in the red box labeled \"1\" you see the \"Actions\" tab of the " +"GitHub repository. On the left, in the red box labeled \"2\" you can see " +"the name of the workflow, as configured in this step. Finally, in the " +"center, in the red box labeled \"3\" you can see several runs of the " +"workflow, for the \"1.0\" and \"1.0.1\" releases of the package." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:73 +msgid "Step 2: Add triggers to the workflow" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:75 +msgid "" +"Every GitHub Actions workflow runs when [certain " +"conditions](https://docs.github.com/en/actions/reference/events-that-" +"trigger-workflows) are met. In this case, we assume that a release " +"workflow should only run when the repository owner creates a new " +"[release](https://docs.github.com/en/repositories/releasing-projects-on-" +"github/managing-releases-in-a-repository) for the package. Add the " +"following to the `release.yaml` file to ensure it runs when you create " +"and publish a release:" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:87 +msgid "Step 3: Configure the jobs in the workflow" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:89 +msgid "" +"A GitHub Actions *workflow* file can contain multiple *jobs* that run " +"independently; each job can also have multiple *steps.* When triggered, " +"the GitHub Action runs all the jobs in a workflow (excluding any steps " +"that have conditional requirements)." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:93 +msgid "" +"Jobs and steps can also have [conditional " +"logic](https://docs.github.com/en/actions/reference/workflow-syntax-for-" +"github-actions#jobsjob_idif) that allows them only to run if specific " +"criteria exist. For instance, you may want only to have a job step to " +"publish to PyPI if a release was made for the package. But you might want" +" to test building the package every time you merge a new pull request." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:96 +msgid "" +"For a release job, you need to clone or check out the repository. You can" +" use the `actions/checkout` action to check out the code. You then " +"install and use [Hatch](get-to-know-hatch) to build your package." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:101 +msgid "" +"You also need to make sure to set up Hatch on the machine GitHub is using" +" to run the workflow." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:104 +msgid "A minimal job definition would look like this:" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:124 +msgid "" +"Notice that above, you provide a version for each action step. " +"`action/checkout@v5` tells GitHub to use version 5 of the checkout " +"action. The checkout action checks out the code from your repository. In " +"this case, the code will be used to build your package." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:126 +msgid "" +"Next, you will learn about a better way to secure (or \"harden\") your " +"workflow" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:128 +msgid "Step 4: Secure the GitHub Actions workflow" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:130 +msgid "" +"There are several improvements you can make to the GitHub Actions " +"workflow you just configured to improve security and readability." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:133 +msgid "" +"First, we can give names to relevant steps in the process to increase the" +" readability of the logs generated during the workflow run. This can be " +"achieved using `name: ` lines." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:137 +msgid "" +"More importantly, each time you use an existing action (via `uses`) you " +"should pin that action to a commit hash. Pinning your action ensures that" +" if a malicious user takes over the action, they won't be able to impact " +"your repository (an example of a supply chain attack due to GitHub " +"Actions is the recent `tj-actions/changed-files` attack[^changed-files-" +"supply-chain-attack])." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:144 +msgid "" +"Enabling Dependabot[^dependabot] in the repository will ensure that your " +"actions stay up to date. The dependabot tool will open pull requests that" +" update your action versions at whatever frequency you want." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:149 +msgid "Thus, the workflow that you should use should be similar to:" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:157 +msgid "" +"Now, you can commit the `.github/workflows/release.yaml` file to the " +"repository and push to GitHub." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:159 +msgid "" +"At this point, if you create a new release for your project on GitHub, " +"the configured workflow should run and build a wheel for you. " +"Unfortunately, the wheel is only available on the runner and will be " +"deleted at the end of the workflow run." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:163 +msgid "Step 5: Upload the built artifact to GitHub Artifacts" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:165 +msgid "" +"You need to add one more step to the job definition to be able to access " +"the wheel. You will upload it to the artifacts temporary area[^github-" +"artifacts]. Add the following to the `release.yaml` file:" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:175 +msgid "Upload artifacts parameters" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:178 +msgid "" +"Above, you have configured the artifact to be deleted after 1 day. The " +"artifacts storage on GitHub actions is temporary; users should not " +"download your package from the GitHub artifacts." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:181 +msgid "" +"You have also configured the release job to error if the `dist/` " +"directory does not exist. This means that `hatch build` (from the " +"previous step) failed to build our package, so there is nothing to " +"release." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:186 +msgid "" +"At this point, if you push the `release.yaml` to GitHub and create a new " +"release, the GitHub Actions job will:" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:189 +msgid "run," +msgstr "" + +#: ../../tutorials/trusted-publishing.md:190 +msgid "clone your repository," +msgstr "" + +#: ../../tutorials/trusted-publishing.md:191 +msgid "install and set up Hatch," +msgstr "" + +#: ../../tutorials/trusted-publishing.md:192 +msgid "build your package and" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:193 +msgid "upload your package as an archive to the artifacts storage." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:196 +msgid "" +"Graphic showing an example of a release workflow that has just finished " +"running. Each step in the log is matched to one step in the workflow " +"definition." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:198 +msgid "" +"This figure shows an example of a release workflow that has just finished" +" running. Each step in the log is matched to one step in the workflow " +"definition." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:201 +msgid "" +"At the bottom of the workflow run page on GitHub, you should see a " +"section for the artifacts produced during runtime and uploaded to this " +"storage area:" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:205 +msgid "" +"Graphic showing an example of an artifact produced by the release " +"workflow." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:207 +msgid "" +"This figure shows the artifact produced by the above release workflow. It" +" is now marked as expired since the workflow ran more than a day ago." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:210 +msgid "" +"You can download the artifact (before it expires), unzip it, and install " +"the wheel contained within. However, this should only be done if you want" +" to test the built wheel. Next, you will configure uploading to PyPI " +"using trusted publishing." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:215 +msgid "Configure automatic publishing to PyPI" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:217 +msgid "" +"The job you configured above using GitHub Actions builds your package " +"using your code. You still need to upload it to PyPI. You could upload " +"the package from the same job, but it is better to create a separate one " +"to maintain a separation of tasks. This is why, in the previous section, " +"we uploaded the artifact to the temporary storage." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:223 +msgid "" +"In the new job, you will download the package from there and upload it to" +" PyPI. Since the `build` job does nothing else, there is no possibility " +"that the package could get compromised before the release." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:227 +msgid "Step 1: Add the upload job" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:229 +msgid "" +"In the `release.yaml` file, add the following new job, after the job " +"defined in the previous section:" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:238 +msgid "Make sure to change the URL" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:240 +msgid "Remember to change the `url:` value to the URL for your package on PyPI!" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:243 +msgid "This job has two steps:" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:245 +msgid "" +"It uses `download-artifact` to download the artifacts built in the " +"previous job" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:247 +msgid "It uses `gh-action-pypi-publish` to publish the package to PyPI." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:249 +msgid "" +"You are almost there!! Now, you just need to enable trusted publishing " +"for your project on PyPI. And then, your work is done!" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:252 +msgid "Step 2: Enable trusted publishing on PyPI" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:256 +msgid "" +"Diagram showing PyPI's trusted publisher workflow: Step 1 builds " +"distribution files via GitHub, Step 2 uses a trusted environment (PyPI), " +"Step 3 securely uploads to PyPI. Shows chain of trust with lock icon " +"connecting GitHub Action to Python Package Index." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:261 +msgid "" +"Before trusted publishing was created, in order to upload to PyPI from " +"GitHub actions you would have needed to add the username and password as " +"arguments to the `gh-action-pypi-publish` step. While documentation " +"recommends using the GitHub's `secrets` environment for the " +"password/token, in several cases, users were pasting the password " +"directly into the workflow file. Furthermore, accidental leakage of the " +"password or token could allow attackers to publish new packages using " +"your account, until you discover the compromise and revoke the leaked " +"credentials." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:269 +msgid "" +"To prevent these incidents and improve supply chain security, developers " +"created [Trusted Publishing](https://docs.pypi.org/trusted-publishers/). " +"Trusted publishing allows you to register a publishing workflow on PyPI " +"and then map that workflow to an automation workflow (e.g., GitHub " +"Actions) that is allowed to publish the package." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:274 +msgid "" +"You do not need to enter a token or password value in a trusted publisher" +" workflow. It's a secure connection between your" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:277 +msgid "Trusted Publishing outside of GitHub Actions" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:280 +msgid "" +"Trusted Publishing supports other automation platforms, beyond GitHub " +"Actions. It is also possible to configure a trusted publisher for " +"multiple workflows or multiple publishers for the same package. These are" +" advanced uses, out of scope for this lesson." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:286 +msgid "" +"For this lesson, we will focus on configuring a trusted publisher for a " +"project that already exists on PyPI. If you completed the [lesson about " +"PyPI publishing](create-python-package), you should have this project " +"already created." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:288 +msgid "" +"This setup step needs to be performed only once for the project. Future " +"releases will only run the GitHub Actions workflow we are configuring in " +"`release.yaml`." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:291 +msgid "" +"On the [\"Your projects\" page on " +"PyPI](https://pypi.org/manage/projects/), click \"Manage\" on any project" +" you want to configure." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:295 +msgid "" +"Graphic showing a screenshot of the \"Your projects\" page on PyPI. The " +"\"Manage\" button for one of the projects is highlighted." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:297 +msgid "" +"This image shows several projects. The \"Manage\" button is highlighted " +"for one of the projects, the one we want to configure trusted publishing " +"for." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:300 +msgid "Then click \"Publishing\" in the project's sidebar." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:303 +msgid "" +"Graphic showing the management page for one project. The \"Publishing\" " +"link in the sidebar is highlighted." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:305 +msgid "" +"Once clicking on the \"Manage\" button we got to the project's page. In " +"the sidebar, we have the \"publishing\" option, as highlighted here." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:309 +msgid "" +"This will take you to the publisher configuration page for the project. " +"Trusted publishers can be configured via the forms here. Fill in the " +"GitHub form with the following information:" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:313 +msgid "" +"Owner: the GitHub organization name for the organization that owns the " +"project. If this is your personal project, then use your GitHub username " +"here." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:315 +msgid "Repository name: the name of the repository that contains the project." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:316 +msgid "" +"Workflow name: Should be `release.yaml` if you followed this guide, it is" +" the workflow we just configured." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:318 +msgid "" +"Environment name: Should be `pypi`, as that is what we configured in " +"`release.yaml`." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:321 +msgid "" +"Once you fill in this form and click \"Add\" the publisher is configured " +"and can be used to publish new releases of your package." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:324 +msgid "Fully hardened GitHub Actions release workflow" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:326 +msgid "" +"For better security, it is also recommended to control the permissions of" +" the GitHub token used within each job of the workflow. The permissions " +"should be scoped at job level and be as minimal as possible. A workflow " +"that configures trusted publishing and also does this is the following:" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:336 +msgid "" +"You can copy the above into your `release.yaml` file. You only need to " +"update the `url:` field and configure trusted publishing on PyPI." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:340 +msgid "" +"The workflow above should be up to date with the current versions of " +"GitHub actions. However, it's good to turn on Dependabot to update the " +"action versions in the future." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:343 +msgid "You have enabled trusted publishing for your project" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:345 +msgid "" +"Congratulations!! You have now configured your project to do secure " +"releases when a new version is being tagged on GitHub. The workflow we " +"have configured builds the package from the exact version of code that we" +" are tagging. This provides a guarantee for your users that the package " +"that you have released does precisely what the code states it does. There" +" is little to no potential for supply chain related vulnerabilities " +"arising from your package! If you have a package that is ready for real-" +"world use on the real PyPI, then you can follow the same steps to publish" +" it securely." +msgstr "" + +#: ../../tutorials/trusted-publishing.md:349 +msgid "" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:350 +msgid "" +"" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:351 +msgid "" +"" +msgstr "" + +#: ../../tutorials/trusted-publishing.md:352 +msgid "" +msgstr ""