From 6b86269520150413e97c2368287e3ab5dc85ee38 Mon Sep 17 00:00:00 2001 From: Felipe Moreno Date: Wed, 3 Jul 2024 17:00:50 -0400 Subject: [PATCH] Create empty translation files --- locales/es/LC_MESSAGES/CONTRIBUTING.po | 414 ++ locales/es/LC_MESSAGES/TRANSLATING.po | 717 +++ locales/es/LC_MESSAGES/documentation.po | 2545 ++++++++ .../es/LC_MESSAGES/package-structure-code.po | 5301 ++++++++++++++++ locales/es/LC_MESSAGES/tutorials.po | 5417 +++++++++++++++++ 5 files changed, 14394 insertions(+) create mode 100644 locales/es/LC_MESSAGES/CONTRIBUTING.po create mode 100644 locales/es/LC_MESSAGES/TRANSLATING.po create mode 100644 locales/es/LC_MESSAGES/documentation.po create mode 100644 locales/es/LC_MESSAGES/package-structure-code.po create mode 100644 locales/es/LC_MESSAGES/tutorials.po diff --git a/locales/es/LC_MESSAGES/CONTRIBUTING.po b/locales/es/LC_MESSAGES/CONTRIBUTING.po new file mode 100644 index 00000000..b2a801f4 --- /dev/null +++ b/locales/es/LC_MESSAGES/CONTRIBUTING.po @@ -0,0 +1,414 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2024, pyOpenSci +# This file is distributed under the same license as the pyOpenSci Python +# Package Guide package. +# FIRST AUTHOR , 2024. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: pyOpenSci Python Package Guide \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-07-03 16:27-0400\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: es\n" +"Language-Team: es \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.15.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." +msgstr "" + +#: ../../CONTRIBUTING.md:37 +msgid "" +"*__TODO__: This section should show a beginner user how to fork a " +"repository in GitHub.*" +msgstr "" + +#: ../../CONTRIBUTING.md:39 +msgid "Contributing via the GitHub website" +msgstr "" + +#: ../../CONTRIBUTING.md:41 +msgid "How to edit a MarkDown file" +msgstr "" + +#: ../../CONTRIBUTING.md:43 +msgid "" +"*__TODO__: This section should show how to use the GitHub interface to " +"edit and previewing a Markdown file.*" +msgstr "" + +#: ../../CONTRIBUTING.md:45 +msgid "How to commit your changes" +msgstr "" + +#: ../../CONTRIBUTING.md:47 +msgid "" +"*__TODO__: This section should show how to commit changes via the GitHub " +"interface.*" +msgstr "" + +#: ../../CONTRIBUTING.md:49 +msgid "Contributing locally on your computer" +msgstr "" + +#: ../../CONTRIBUTING.md:51 +msgid "Clone your forked repository" +msgstr "" + +#: ../../CONTRIBUTING.md:53 +msgid "" +"*__TODO__: This section should show how to clone a repository from GitHub" +" into your computer.*" +msgstr "" + +#: ../../CONTRIBUTING.md:55 +msgid "Create a new branch" +msgstr "" + +#: ../../CONTRIBUTING.md:57 +msgid "*__TODO__: This section should show how to create a new branch.*" +msgstr "" + +#: ../../CONTRIBUTING.md:59 +msgid "Create a virtual environment" +msgstr "" + +#: ../../CONTRIBUTING.md:61 +msgid "" +"*__TODO__: This section should show how to create a virtual environment " +"using venv.*" +msgstr "" + +#: ../../CONTRIBUTING.md:63 +msgid "Install the development dependencies" +msgstr "" + +#: ../../CONTRIBUTING.md:65 +msgid "" +"*__TODO__: This section should show how to install the development " +"dependencies defined in pyproject.toml.*" +msgstr "" + +#: ../../CONTRIBUTING.md:67 +msgid "Commit your changes" +msgstr "" + +#: ../../CONTRIBUTING.md:69 +msgid "" +"*__TODO__: This section should describe how to commit from the command " +"line.*" +msgstr "" + +#: ../../CONTRIBUTING.md:71 +msgid "How to build the guide locally" +msgstr "" + +#: ../../CONTRIBUTING.md:73 +msgid "" +"*__TODO__: This section should describe the different sessions in nox " +"related to building the docs: docs, docs-test, docs-live. It should also " +"show how to see the guide built locally, by opening the right file in the" +" browser or using the live version from docs-live*" +msgstr "" + +#: ../../CONTRIBUTING.md:75 +msgid "Before you submit your pull request" +msgstr "" + +#: ../../CONTRIBUTING.md:77 +msgid "" +"*__TODO__: This section should describe what steps a user should follow " +"before submitting the pull request: build the docs, verify your changes " +"look correct, etc.*" +msgstr "" + +#: ../../CONTRIBUTING.md:79 +msgid "Submitting a pull request with your contribution" +msgstr "" + +#: ../../CONTRIBUTING.md:81 +msgid "How to make a pull request" +msgstr "" + +#: ../../CONTRIBUTING.md:83 +msgid "" +"*__TODO__: This section should describe how to make a pull request in " +"GitHub.*" +msgstr "" + +#: ../../CONTRIBUTING.md:85 +msgid "What happens when you submit a pull request (CI/CD)" +msgstr "" + +#: ../../CONTRIBUTING.md:87 +msgid "" +"*__TODO__: This section should describe how to see the results of the " +"CD/CI checks and how to get more information about errors*" +msgstr "" + +#: ../../CONTRIBUTING.md:89 +msgid "What to expect from the review process" +msgstr "" + +#: ../../CONTRIBUTING.md:91 +msgid "" +"*__TODO__: This section should describe how review happens in GitHub, how" +" see the comments, and how to submit changes (push a new branch)*" +msgstr "" + +#: ../../CONTRIBUTING.md:93 +msgid "Additional help" +msgstr "" + +#: ../../CONTRIBUTING.md:95 +msgid "How to get help" +msgstr "" + +#: ../../CONTRIBUTING.md:97 +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:99 +msgid "Additional resources" +msgstr "" + +#: ../../CONTRIBUTING.md:101 +msgid "" +"*__TODO__: It should also include links to beginner documentation, like " +"the GitHub docs.*" +msgstr "" + +#: ../../CONTRIBUTING.md:103 +msgid "Annex" +msgstr "" + +#: ../../CONTRIBUTING.md:105 +msgid "Code examples" +msgstr "" + +#: ../../CONTRIBUTING.md:107 +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:111 +msgid "Referencing code in documentation" +msgstr "" + +#: ../../CONTRIBUTING.md:113 +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:116 +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:121 +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:125 +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:128 +msgid "Creating code for documentation" +msgstr "" + +#: ../../CONTRIBUTING.md:130 +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:134 +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:138 +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:142 +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:145 +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:153 +msgid "Example:" +msgstr "" + +#: ../../CONTRIBUTING.md:155 +msgid "Instead of writing example code in markdown like this" +msgstr "" + +#: ../../CONTRIBUTING.md:166 +msgid "The python can be extracted into a `.py` file" +msgstr "" + +#: ../../CONTRIBUTING.md:180 +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:183 +msgid "Instead of writing this" +msgstr "" + +#: ../../CONTRIBUTING.md:195 +msgid "an example could be extracted from an existing toml file" +msgstr "" diff --git a/locales/es/LC_MESSAGES/TRANSLATING.po b/locales/es/LC_MESSAGES/TRANSLATING.po new file mode 100644 index 00000000..9c147e7c --- /dev/null +++ b/locales/es/LC_MESSAGES/TRANSLATING.po @@ -0,0 +1,717 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2024, pyOpenSci +# This file is distributed under the same license as the pyOpenSci Python +# Package Guide package. +# FIRST AUTHOR , 2024. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: pyOpenSci Python Package Guide \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-07-03 16:27-0400\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: es\n" +"Language-Team: es \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.15.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 "Overview of the Translation Process" +msgstr "" + +#: ../../TRANSLATING.md:13 +msgid "" +"The process of adapting software to different languages is called " +"internationalization, or i18n for short. Internationalization makes sure " +"that translation can happen without having to modify the source code, or " +"in our case, the original English source files of the guide." +msgstr "" + +#: ../../TRANSLATING.md:15 +msgid "" +"Sphinx, the documentation engine we use to build the Python Package " +"Guide, has built-in support for internationalization, so the workflow is " +"very straightforward." +msgstr "" + +#: ../../TRANSLATING.md:17 +msgid "" +"The process of actually translating the guide into different languages is" +" called localization, or l10n for short. This is the step you will be " +"helping with your contribution." +msgstr "" + +#: ../../TRANSLATING.md:19 +msgid "Here is a quick overview of how the translation process works:" +msgstr "" + +#: ../../TRANSLATING.md:21 +msgid "" +"The guide is originally written in English and stored in a set of " +"MarkDown files." +msgstr "" + +#: ../../TRANSLATING.md:22 +msgid "" +"The source files are processed by Sphinx to generate a set of translation" +" files stored in a folder for each target language." +msgstr "" + +#: ../../TRANSLATING.md:23 +msgid "" +"Contributors (like you!) translate these files into the different " +"languages." +msgstr "" + +#: ../../TRANSLATING.md:24 +msgid "" +"When the guide is built, Sphinx creates a version of the guide in the " +"original language (English) and the translated versions for the languages" +" defined in the configuration." +msgstr "" + +#: ../../TRANSLATING.md:27 +msgid "" +"You don't need to understand the technical details to contribute, but if " +"you are interested in learning how Sphinx handles internationalization " +"and localization, you can find more information [here](https://www" +".sphinx-doc.org/en/master/usage/advanced/intl.html)." +msgstr "" + +#: ../../TRANSLATING.md:30 +msgid "Setting up Your Local Environment" +msgstr "" + +#: ../../TRANSLATING.md:32 +msgid "Before you start, you will need to set up your local work environment." +msgstr "" + +#: ../../TRANSLATING.md:34 +msgid "" +"First, fork the guide repository into your personal GitHub account and " +"clone the forked repository to your local computer." +msgstr "" + +#: ../../TRANSLATING.md:36 +msgid "" +"To create a virtual environment and install the development dependencies " +"for the guide, run the following commands:" +msgstr "" + +#: ../../TRANSLATING.md:45 +msgid "" +"TODO: This section needs more work or to be replaced with a reference to " +"the CONTRIBUTING guide." +msgstr "" + +#: ../../TRANSLATING.md:47 +msgid "Starting a New Language Translation" +msgstr "" + +#: ../../TRANSLATING.md:49 +msgid "" +"If you plan to work on an existing translation, you can skip this step " +"and go directly to the next section." +msgstr "" + +#: ../../TRANSLATING.md:51 ../../TRANSLATING.md:217 +msgid "Important" +msgstr "" + +#: ../../TRANSLATING.md:52 +msgid "" +"If you would like to start the translation of the guide into a new " +"language, start by [creating an issue](https://github.com/pyOpenSci" +"/python-package-guide/issues) in the repository." +msgstr "" + +#: ../../TRANSLATING.md:55 +msgid "" +"To generate the translation files for a new language, add the language to" +" the `LANGUAGES` list in the `noxfile.py` configuration file. " +"[Nox](https://nox.thea.codes/en/stable/index.html) is the tool we use to " +"manage the building of the guide and its translations." +msgstr "" + +#: ../../TRANSLATING.md:57 +msgid "" +"Inside `noxfile.py`, find the `LANGUAGES` list and add the corresponding " +"two-letter code. For example, if you want to start the translation of the" +" guide into French, you would add `'fr'`:" +msgstr "" + +#: ../../TRANSLATING.md:68 +msgid "" +"You can find a list of the two-letter ISO language codes " +"[here](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes)." +msgstr "" + +#: ../../TRANSLATING.md:71 +msgid "Preparing the Translation Files" +msgstr "" + +#: ../../TRANSLATING.md:73 +msgid "" +"The translation files contain the original English text and a space for " +"you to enter the translated text. Before starting to translate, you need " +"to make sure the translation files are up to date with the latest changes" +" to the guide." +msgstr "" + +#: ../../TRANSLATING.md:75 +msgid "You can do this by running the following command:" +msgstr "" + +#: ../../TRANSLATING.md:81 +msgid "" +"This command will create the translation files if they don't exist yet, " +"or update them with the latest changes if they already exist." +msgstr "" + +#: ../../TRANSLATING.md:83 +msgid "" +"The translation files are text files with the `.po` extension stored in " +"the `./locales`, in folders corresponding to each language. For example, " +"the translation files for Spanish are stored in the " +"`locale/es/LC_MESSAGES` directory." +msgstr "" + +#: ../../TRANSLATING.md:85 +msgid "" +"Because the translation files map the original English text to translated" +" text, they are sometimes referred to as \"catalog\" files or \"portable " +"object\" files." +msgstr "" + +#: ../../TRANSLATING.md:88 +msgid "" +"You don't need to know all the details about the PO format in order to " +"translate. If you are interested in learning more, you can find " +"additional details in the [GNU gettext " +"documentation](https://www.gnu.org/software/gettext/manual/html_node/PO-" +"Files.html)." +msgstr "" + +#: ../../TRANSLATING.md:91 +msgid "Working on a Translation" +msgstr "" + +#: ../../TRANSLATING.md:93 +msgid "" +"In order to start translating, go to the folder inside `./locales` " +"corresponding to the target language you want to translate to (for " +"example, `./locale/es/LC_MESSAGES/` for the Spanish translation)." +msgstr "" + +#: ../../TRANSLATING.md:95 +msgid "" +"In this folder you will find a set of `.po` files, corresponding to the " +"different sections of the guide:" +msgstr "" + +#: ../../TRANSLATING.md:111 +msgid "" +"You may also see some `.mo` files in the same folder. These are compiled " +"versions of the `.po` files create by Sphinx during the build process, " +"and used to generate the translated version of the guide. They are " +"intermediary files and are not meant to be edited directly or stored in " +"the repository." +msgstr "" + +#: ../../TRANSLATING.md:114 +msgid "" +"If you are working on a new translation, choose one of the `.po` files to" +" start with. If you are working on an existing translation, you can start" +" with the `.po` files that need the most work." +msgstr "" + +#: ../../TRANSLATING.md:116 +msgid "" +"To see how much of each file has been translated, use the `sphinx-intl " +"stat`. You will be able to see the number of translated, fuzzy, and " +"untranslated strings in each `.po` file." +msgstr "" + +#: ../../TRANSLATING.md:118 +msgid "" +"For example, to see the statistics for the Spanish translation, you would" +" run:" +msgstr "" + +#: ../../TRANSLATING.md:132 +msgid "What do these categories mean:" +msgstr "" + +#: ../../TRANSLATING.md:134 +msgid "" +"Translated strings are strings that have been translated into the target " +"language." +msgstr "" + +#: ../../TRANSLATING.md:135 +msgid "" +"Fuzzy strings are strings that have been translated but need to be " +"reviewed because the original English string in the guide changed." +msgstr "" + +#: ../../TRANSLATING.md:136 +msgid "Untranslated strings are strings that have not been translated yet." +msgstr "" + +#: ../../TRANSLATING.md:139 +msgid "" +"When Sphinx is building the guide in another language, it will look into " +"the corresponding folder in `./locales/` for translated strings. If the " +"translation is available, Sphinx will replace the English text with the " +"equivalent text in the target language. If the translation is not " +"available, Sphinx will use the original English strings." +msgstr "" + +#: ../../TRANSLATING.md:142 +msgid "Editing the Translation Files" +msgstr "" + +#: ../../TRANSLATING.md:144 +msgid "" +"You can use any text editor to edit the `.po` file. But if you prefer, " +"there are also tools like [Poedit](https://poedit.net/) that provide a " +"graphic use interface." +msgstr "" + +#: ../../TRANSLATING.md:146 +msgid "" +"Depending on your editor of choice, you may be able to install a plugin " +"or extension that can provide syntax highlighting and other features for " +"working with `.po` files. Like for example, the " +"[gettext](https://marketplace.visualstudio.com/items?itemName=mrorz" +".language-gettext) extension for Visual Studio Code." +msgstr "" + +#: ../../TRANSLATING.md:148 +msgid "" +"When you open a `.po` file, you will see a series of entries that look " +"like this:" +msgstr "" + +#: ../../TRANSLATING.md:158 +msgid "" +"The first line of an entry starts with `#:` and is a reference to the " +"original source file and line number from which the text was extracted. " +"This information is useful for finding the context of the text in the " +"guide." +msgstr "" + +#: ../../TRANSLATING.md:160 +msgid "" +"The `msgid` field contains the original English text that needs to be " +"translated. The `msgstr` field is where you will enter the translated " +"text. This field might contain text if someone else already translated " +"the entry." +msgstr "" + +#: ../../TRANSLATING.md:170 +msgid "" +"Sometimes the original English text may be too long for a single line, " +"and it may be split into multiple lines. In this case, you can keep the " +"same structure in the translated text. Notice that both the `msgid` and " +"`msgstr` fields in the example below start with an empty string, " +"indicating that the text continues in the next line." +msgstr "" + +#: ../../TRANSLATING.md:186 +msgid "" +"The English text will sometimes contain Markdown formatting, such as bold" +" or italic text. You should keep the formatting in the translated text, " +"making sure to translate the text inside the formatting tags." +msgstr "" + +#: ../../TRANSLATING.md:188 +msgid "" +"The English text may also contain links to other sections of the guide or" +" external resources. You should keep the links in the translated text, " +"making sure to update the link text when appropriate." +msgstr "" + +#: ../../TRANSLATING.md:196 +msgid "" +"An entry may be marked as `fuzzy`, which means that the original English " +"text has changed since the translation was made, and the translation may " +"need to be revised. When this is the case you will see an additional line" +" in the entry, starting with `#,`:" +msgstr "" + +#: ../../TRANSLATING.md:213 +msgid "" +"You can review the translation and make any necessary changes, removing " +"the `fuzzy` tag once you are satisfied with the translation." +msgstr "" + +#: ../../TRANSLATING.md:215 +msgid "" +"You can also add comments to the translation file, by adding lines that " +"start with a `#` character to the entry. This can be helpful to add " +"context to the translation for other translators or reviewers to see, but" +" this might be only necessary in special circumstances." +msgstr "" + +#: ../../TRANSLATING.md:218 +msgid "" +"When working on a translation, you **should not** modify the original " +"English text in the `msgid` field. If you see a typo or an error in the " +"original text, please consider fixing it in the original source file (use" +" the first line of the entry to locate it) and submit a separate pull " +"request." +msgstr "" + +#: ../../TRANSLATING.md:221 +msgid "Building the Translated Documentation" +msgstr "" + +#: ../../TRANSLATING.md:223 +msgid "" +"Once you finished translating or when you want to check the translation " +"in context, you can build the guide locally on your computer, using the " +"following command:" +msgstr "" + +#: ../../TRANSLATING.md:229 +msgid "" +"This command will build all the translated versions of the guide defined " +"in the `LANGUAGES` list in `noxfile.py`. These translations will be " +"stored in the `_build/html`, in folders named after the language code " +"(e.g., `es`, `fr`, etc.)." +msgstr "" + +#: ../../TRANSLATING.md:231 +msgid "" +"To view the translated version of the guide in your browser, open the " +"corresponding `index.html` file. For example, to view the Spanish " +"translation, you would open `_build/html/es/index.html`." +msgstr "" + +#: ../../TRANSLATING.md:233 +msgid "" +"You can also build a live version of the guide that updates automatically" +" as you make changes to the translation files. To do this, use the `nox " +"-s docs-live-lang` command. Note that in this case you need to specify " +"which language you want to build. For example, if you are working on the " +"Spanish translation, you would run:" +msgstr "" + +#: ../../TRANSLATING.md:239 +msgid "" +"Note the `--` before the language code, it indicates that the following " +"arguments should be passed into the nox session and not be interpreted " +"directly by nox. If you forget the `--`, nox will look instead for a " +"session named 'es' and complain that it does not exist." +msgstr "" + +#: ../../TRANSLATING.md:241 +msgid "" +"This command will use `sphinx-autobuild` to launch a local web server " +"where you can access the translated version of the guide. You can open " +"the guide in your browser by navigating to `http://localhost:8000`." +msgstr "" + +#: ../../TRANSLATING.md:243 +msgid "" +"This is a great way to see how the translated version of the guide looks " +"as you make changes to the translation files." +msgstr "" + +#: ../../TRANSLATING.md:245 +msgid "Submitting a PR for Your Contribution" +msgstr "" + +#: ../../TRANSLATING.md:247 +msgid "" +"Once you are finished translating and before you submit a pull request " +"(PR) for your translation, you need to make sure that the translated " +"version of the guide builds without any errors or warning and looks " +"correctly in the browser." +msgstr "" + +#: ../../TRANSLATING.md:249 +msgid "You can follow these steps:" +msgstr "" + +#: ../../TRANSLATING.md:251 +msgid "" +"Build the translations of the guide with same parameters that will be " +"used during the release:" +msgstr "" + +#: ../../TRANSLATING.md:257 +msgid "" +"Make sure there are no warnings or errors in the output. If there are, " +"you will need to fix them before submitting the PR." +msgstr "" + +#: ../../TRANSLATING.md:258 +msgid "" +"Make sure the translated version of the guide looks good in the browser " +"by opening the `_build/html//index.html` file, where `` is " +"the language you have been working on." +msgstr "" + +#: ../../TRANSLATING.md:260 +msgid "If everything looks good, you can submit a PR with your changes." +msgstr "" + +#: ../../TRANSLATING.md:263 +msgid "" +"When you submit a PR for a translation, you should only include changes " +"to one language. If you worked in multiple languages, please submit a " +"separate PR for each language." +msgstr "" + +#: ../../TRANSLATING.md:266 +msgid "" +"Translations PRs will be tagged with a label indicating the language to " +"make them easier to identify and review. For example, contributions to " +"the Spanish translation will be tagged with 'lang-es'." +msgstr "" + +#: ../../TRANSLATING.md:268 +msgid "TODO: This tagging could be automated with a GitHub action." +msgstr "" + +#: ../../TRANSLATING.md:270 +msgid "" +"When you submit the PR, make sure to include a short description of the " +"changes you made and any context that might be helpful for the reviewer " +"(e.g., you translated new strings, you reviewed fuzzy entries, you fixed " +"typos, etc.)" +msgstr "" + +#: ../../TRANSLATING.md:272 +msgid "The Review Process" +msgstr "" + +#: ../../TRANSLATING.md:274 +msgid "" +"The review process for a translation contribution is similar to the " +"review process for any other contribution to the guide." +msgstr "" + +#: ../../TRANSLATING.md:276 +msgid "" +"TODO: This section needs more work, depending on the review workflow we " +"decide to adopt. Other projects usually assign a coordinator/editor for " +"each language, who is responsible for reviewing and merging translation " +"contributions." +msgstr "" + +#: ../../TRANSLATING.md:278 +msgid "" +"Each language has an assigned editor who is responsible for reviewing and" +" merging translation contributions. The editor will review the changes to" +" make sure they are accurate and consistent with the style and tone of " +"the guide." +msgstr "" + +#: ../../TRANSLATING.md:280 +msgid "" +"Sometimes the editor may ask for clarification or suggest changes to " +"improve the translation. If this happens, you can make the requested " +"changes and push them to the same branch where you submitted the original" +" PR." +msgstr "" + +#: ../../TRANSLATING.md:282 +msgid "" +"When the editor is satisfied with the translation, they will merge the " +"PR. The translated version of the guide will be available on the " +"pyOpenSci website once the language is released." +msgstr "" + +#: ../../TRANSLATING.md:284 +msgid "The Release Process" +msgstr "" + +#: ../../TRANSLATING.md:286 +msgid "" +"If a language is ready to go live, the maintainers will add the language " +"code to the `RELEASE_LANGUAGES` list in the `noxfile.py` configuration " +"file." +msgstr "" + +#: ../../TRANSLATING.md:288 +msgid "" +"When the guide is built for release in CI, Sphinx will also generate the " +"translated versions of the guide for the languages in the " +"`RELEASE_LANGUAGES` list." +msgstr "" + +#: ../../TRANSLATING.md:290 +msgid "" +"Translations are released in the same way as the English version of the " +"guide, and the translated versions will be available in folders named " +"after the language code. For example, the Spanish translation will be " +"available in [https://www.pyopensci.org/python-package-" +"guide/es/](https://www.pyopensci.org/python-package-guide/es/)." +msgstr "" + +#: ../../TRANSLATING.md:292 +msgid "Frequently Asked Questions (FAQ)" +msgstr "" + +#: ../../TRANSLATING.md:294 +msgid "How do I know which strings need to be translated?" +msgstr "" + +#: ../../TRANSLATING.md:296 +msgid "" +"When you run the `sphinx-intl stat` command, you will see a list of `.po`" +" files with the number of translated, fuzzy, and untranslated strings. " +"You can start by working on the files with the most untranslated strings." +msgstr "" + +#: ../../TRANSLATING.md:298 +msgid "What happens when a string has changed in the original English text?" +msgstr "" + +#: ../../TRANSLATING.md:300 +msgid "" +"If a string has changed in the original English version, it will be " +"marked as `fuzzy` in the translation file the next time it is updated " +"(`nox -s update-translations`). Contributors working on the translation " +"can then review the fuzzy entries and make the necessary changes to " +"ensure it is accurate, before removing the `fuzzy` tag." +msgstr "" + +#: ../../TRANSLATING.md:302 +msgid "How do I handle links in the translated text?" +msgstr "" + +#: ../../TRANSLATING.md:304 +msgid "" +"You should keep the links in the translated text, but make sure to update" +" the link text if necessary. For example, if the original English text " +"contains a link to `[What is a Python package?](/tutorials/intro)`, you " +"should keep the link in the translated text but update the link text to " +"`[¿Que es un paquete de Python?](/tutorials/intro)`." +msgstr "" + +#: ../../TRANSLATING.md:306 +msgid "How do I handle formatting in the translated text?" +msgstr "" + +#: ../../TRANSLATING.md:308 +msgid "" +"You should keep the formatting in the translated text, but make sure to " +"translate the text inside the formatting tags as well. For example, if " +"the original English text is `**Test special cases:**`, you should keep " +"the bold formatting in the translated text but update the text inside the" +" formatting tags to `**Prueba casos especiales:**`." +msgstr "" + +#: ../../TRANSLATING.md:310 +msgid "How do I handle strings that are too long for a single line?" +msgstr "" + +#: ../../TRANSLATING.md:312 +msgid "" +"If the original English text is too long for a single line, it may be " +"split into multiple lines. Multiline strings in the `.po` file are " +"indicated by an empty string in the `msgid` and `msgstr` fields, followed" +" by the continuation of the text in the next line. For example:" +msgstr "" + +#: ../../TRANSLATING.md:325 +msgid "How do I translate images?" +msgstr "" + +#: ../../TRANSLATING.md:327 +msgid "" +"You should not translate images in the guide. Producing translated " +"versions of images is a complex process that requires additional tools " +"and resources, and it is not typically done unless the translated images " +"are created alongside the original images. More often, the text around " +"the image is modified to include any necessary translations." +msgstr "" + +#: ../../TRANSLATING.md:329 +msgid "" +"In some special cases, an image might be critical to the understanding of" +" the content. In those cases, the translations will be handled by the " +"maintainers and editors outside this workflow." +msgstr "" + +#: ../../TRANSLATING.md:331 +msgid "" +"I am interested in translating the guide into a language that is not " +"listed. How can I get started?" +msgstr "" + +#: ../../TRANSLATING.md:333 +msgid "" +"If you want to start a new translation of the guide into a language that " +"is not listed, you should [create an issue](https://github.com/pyOpenSci" +"/python-package-guide/issues) in the repository to let the maintainers " +"know that you intend to work on it. This will help avoid duplication of " +"effort and ensure that the maintainers are ready to review your " +"contribution when you are done." +msgstr "" + +#: ../../TRANSLATING.md:335 +msgid "How do I know when a translation is ready to be released?" +msgstr "" + +#: ../../TRANSLATING.md:337 +msgid "" +"When a translation is ready to be included in the next release of the " +"guide, the maintainers will add the language code to the " +"`RELEASE_LANGUAGES` list in the `noxfile.py` configuration file. This " +"will trigger the build of the translation during the release process, and" +" the translated version of the guide will be available on the pyOpenSci " +"website." +msgstr "" + +#: ../../TRANSLATING.md:339 +msgid "" +"TODO: There are many approaches here, some projects release a translation" +" as soon as some strings are translated, others wait until a certain " +"percentage of the content is translated." +msgstr "" + +#: ../../TRANSLATING.md:341 +msgid "How can I get help with my translation?" +msgstr "" + +#: ../../TRANSLATING.md:343 +msgid "" +"If you have any questions or need help with your translation, you can " +"create an issue in the repository if you encounter any problems or need " +"assistance." +msgstr "" + +#: ../../TRANSLATING.md:345 +msgid "" +"TODO: Maybe [Discourse](https://pyopensci.discourse.group/) could be used" +" as a way for contributors to ask for help with translations or the " +"translation workflow?" +msgstr "" diff --git a/locales/es/LC_MESSAGES/documentation.po b/locales/es/LC_MESSAGES/documentation.po new file mode 100644 index 00000000..2f34859e --- /dev/null +++ b/locales/es/LC_MESSAGES/documentation.po @@ -0,0 +1,2545 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2024, pyOpenSci +# This file is distributed under the same license as the pyOpenSci Python +# Package Guide package. +# FIRST AUTHOR , 2024. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: pyOpenSci Python Package Guide \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-06-28 08:42-0400\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: es\n" +"Language-Team: es \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.15.0\n" + +#: ../../documentation/hosting-tools/intro.md:1 +msgid "Tools to Build and Host your Documentation" +msgstr "" + +#: ../../documentation/hosting-tools/intro.md:3 +msgid "" +"The most common tool for building documentation in the Python ecosystem " +"currently is Sphinx. However, some maintainers are using tools like " +"[mkdocs](https://www.mkdocs.org/) for documentation. It is up to you to " +"use the platform that you prefer for your documentation!" +msgstr "" + +#: ../../documentation/hosting-tools/intro.md:8 +msgid "" +"In this section, we introduce Sphinx as a common tool to build " +"documentation. We talk about various syntax options that you can use when" +" writing Sphinx documentation including mySt and rST." +msgstr "" + +#: ../../documentation/hosting-tools/intro.md:12 +msgid "" +"We also talk about ways to publish your documentation online and Sphinx " +"tools that might help you optimize your documentation website." +msgstr "" + +#: ../../documentation/hosting-tools/myst-markdown-rst-doc-syntax.md:1 +msgid "Documentation syntax: markdown vs. myST vs. rst syntax to create your docs" +msgstr "" + +#: ../../documentation/hosting-tools/myst-markdown-rst-doc-syntax.md:3 +msgid "There are three commonly used syntaxes for creating Python documentation:" +msgstr "" + +#: ../../documentation/hosting-tools/myst-markdown-rst-doc-syntax.md:4 +msgid "" +"[markdown](https://www.markdownguide.org/): Markdown is an easy-to-learn " +"text syntax. It is the default syntax used in Jupyter Notebooks. There " +"are tools that you can add to a Sphinx website that allow it to render " +"markdown as html. However, using markdown to write documentation has " +"limitations. For instance if you want to add references, colored call out" +" blocks and other custom elements to your documentation, you will need to" +" use either **myST** or **rST**." +msgstr "" + +#: ../../documentation/hosting-tools/myst-markdown-rst-doc-syntax.md:8 +msgid "" +"[rST (ReStructured Text):](https://www.sphinx-" +"doc.org/en/master/usage/restructuredtext/basics.html). **rST** is the " +"native syntax that sphinx supports. rST was the default syntax used for " +"documentation for many years. However, in recent years myST has risen to " +"the top as a favorite for documentation given the flexibility that it " +"allows." +msgstr "" + +#: ../../documentation/hosting-tools/myst-markdown-rst-doc-syntax.md:9 +msgid "" +"[myST:](https://myst-parser.readthedocs.io/en/latest/intro.html) myST is " +"a combination of vanilla of `markdown` and `rST` syntax. It is a nice " +"option if you are comfortable writing markdown. `myst` is preferred by " +"many because it offers both the rich functionality of rST combined with a" +" simple-to-write markdown syntax." +msgstr "" + +#: ../../documentation/hosting-tools/myst-markdown-rst-doc-syntax.md:12 +msgid "" +"While you can chose to use any of the syntaxes listed above, we suggest " +"using `myST` because:" +msgstr "" + +#: ../../documentation/hosting-tools/myst-markdown-rst-doc-syntax.md:15 +msgid "It is a simpler syntax and thus easier to learn;" +msgstr "" + +#: ../../documentation/hosting-tools/myst-markdown-rst-doc-syntax.md:16 +msgid "" +"The above simplicity will make it easier for more people to contribute to" +" your documentation." +msgstr "" + +#: ../../documentation/hosting-tools/myst-markdown-rst-doc-syntax.md:17 +msgid "" +"Most of your core Python package text files, such as your README.md file," +" are already in `.md` format" +msgstr "" + +#: ../../documentation/hosting-tools/myst-markdown-rst-doc-syntax.md:18 +msgid "" +"`GitHub` and `Jupyter Notebooks` support markdown thus it's more widely " +"used in the scientific ecosystem." +msgstr "" + +#: ../../documentation/hosting-tools/myst-markdown-rst-doc-syntax.md:22 +msgid "" +"If you are on the fence about myST vs rst, you might find that **myST** " +"is easier for more people to contribute to." +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:1 +msgid "How to publish your Python package documentation online" +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:3 +msgid "" +"We suggest that you setup a hosting service for your Python package " +"documentation. Two free and commonly used ways to quickly create a " +"documentation website hosting environment are below." +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:7 +msgid "" +"You can host your documentation yourself using [GitHub " +"Pages](https://pages.github.com/) or another online hosting service." +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:8 +msgid "" +"You can host your documentation using [Read the " +"Docs](https://readthedocs.org/)." +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:10 +msgid "What is Read the Docs ?" +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:11 +msgid "" +"[Read the Docs](https://readthedocs.org/) is a documentation hosting " +"service that supports publishing your project's documentation." +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:13 +msgid "" +"Read the Docs is a fully featured, free, documentation hosting service. " +"Some of its many features include:" +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:16 +msgid "" +"Is free to host your documentation (but there are also paid tiers if you " +"wish to customize hosting)" +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:17 +msgid "Automates building your documentation" +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:18 +msgid "" +"Allows you to turn on integration with pull requests where you can view " +"documentation build progress (success vs failure)." +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:19 +msgid "" +"Supports versioning of your documentation which allows users to refer to " +"older tagged versions of the docs if they are using older versions of " +"your package." +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:20 +msgid "Supports downloading of documentation in PDF and other formats." +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:21 +msgid "" +"You can customize the documentation build using a **.readthedocs.yaml** " +"file in your GitHub repository." +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:24 +msgid "What is GitHub Pages?" +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:25 +msgid "" +"[GitHub Pages](https://docs.github.com/en/pages/getting-started-with-" +"github-pages/about-github-pages) is a free web hosting service offered by" +" GitHub. Using GitHub pages, you can build your documentation locally or " +"using a Continuous Integration setup, and then push to a branch in your " +"GitHub repository that is setup to run the GitHub Pages web build." +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:33 +msgid "Read the Docs vs GitHub Pages" +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:35 +msgid "" +"GitHub pages is a great option for your documentation deployment. " +"However, you will need to do a bit more work to build and deploy your " +"documentation if you use GitHub pages." +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:39 +msgid "" +"Read the Docs can be setup in your Read the Docs user account. The " +"service automates the entire process of building and deploying your " +"documentation." +msgstr "" + +#: ../../documentation/hosting-tools/publish-documentation-online.md:42 +msgid "" +"If you don't want to maintain a documentation website for your Python " +"package, we suggest using the Read the Docs website." +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:1 +msgid "Using Sphinx to Build Python Package Documentation" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:17 +msgid "" +"On this page we discuss using [Sphinx](https://www.sphinx-doc.org/) to " +"build your user-facing package documentation. While Sphinx is currently " +"the most commonly-used tool in the scientific Python ecosystem, you are " +"welcome to explore other tools to build documentation such as " +"[mkdocs](https://www.mkdocs.org/) which is gaining popularity in the " +"Python packaging ecosystem." +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:25 +msgid "Examples of documentation websites that we love:" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:27 +msgid "[GeoPandas](https://geopandas.org/en/stable/)" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:28 +msgid "" +"[View rst to create landing " +"page](https://raw.githubusercontent.com/geopandas/geopandas/main/doc/source/index.rst)" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:29 +msgid "[verde](https://www.fatiando.org/verde/latest/)" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:30 +msgid "" +"[View verde landing page code - rst " +"file.](https://github.com/fatiando/verde/blob/main/doc/index.rst)" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:31 +msgid "" +"[Here is our documentation if you want to see a myST example of a landing" +" page.](https://github.com/pyOpenSci/python-package-" +"guide/blob/main/index.md)" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:34 +msgid "Sphinx - a static site generator" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:36 +msgid "" +"Sphinx is a [static-site " +"generator](https://www.cloudflare.com/learning/performance/static-site-" +"generator/). A static site generator is a tool that creates html for a " +"website based upon a set of templates. The html files are then served " +"\"Statically\" which means that there is no generation or modification of" +" the files on the fly." +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:39 +msgid "Sphinx is written using Python." +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:41 +msgid "Sphinx sites can be customized using extensions and themes" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:43 +msgid "" +"The functionality of Sphinx can be extended using extensions and themes. " +"A few examples include:" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:46 +msgid "" +"You can apply documentation themes for quick generation of beautiful " +"documentation." +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:47 +msgid "" +"You can [automatically create documentation for your package's functions " +"and classes (the package's API) from docstrings in your code using the " +"autodoc extension](https://www.sphinx-" +"doc.org/en/master/usage/extensions/autodoc.html)" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:48 +msgid "" +"You can [run and test code examples in your docstrings using the doctest " +"extension](https://www.sphinx-" +"doc.org/en/master/usage/extensions/doctest.html)" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:49 +msgid "" +"While Sphinx natively supports the `rST` syntax. You can add custom " +"syntax parsers to support easier-to-write syntax using tools such as [the" +" MyST parser](https://myst-parser.readthedocs.io/)." +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:51 +msgid "Commonly used Sphinx themes" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:53 +msgid "" +"You are free to use whatever Sphinx theme that you prefer. However, the " +"most common Sphinx themes used in the Python scientific community " +"include:" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:57 +msgid "[pydata-sphinx-theme](https://pydata-sphinx-theme.readthedocs.io/)" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:58 +msgid "[sphinx-book-theme](https://sphinx-book-theme.readthedocs.io/)" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:59 +msgid "[furo](https://pradyunsg.me/furo/quickstart/)" +msgstr "" + +#: ../../documentation/hosting-tools/sphinx-python-package-documentation-tools.md:63 +msgid "This book is created using Sphinx and the `furo` theme." +msgstr "" + +#: ../../documentation/hosting-tools/website-hosting-optimizing-your-docs.md:1 +msgid "Optimizing your documentation so search engines (and other users) find it" +msgstr "" + +#: ../../documentation/hosting-tools/website-hosting-optimizing-your-docs.md:3 +msgid "" +"If you are interested in more people finding your package, you may want " +"to add some core Sphinx extensions (and theme settings) that will help " +"search engines such as Google find your documentation." +msgstr "" + +#: ../../documentation/hosting-tools/website-hosting-optimizing-your-docs.md:7 +msgid "Google Analytics" +msgstr "" + +#: ../../documentation/hosting-tools/website-hosting-optimizing-your-docs.md:11 +msgid "" +"Google analytics [is not compliant with the European General Data " +"Protection Regulation (GDPR)](https://matomo.org/blog/2022/05/google-" +"analytics-4-gdpr/). While there are many components to this regulation, " +"one of the core elements is that you have to let users know on your site " +"that you are collecting data and they have to consent. While it is " +"possible to add infrastructure around Google Analytics to make it close " +"to following GDPR regulations, the community is slowly shifting away from" +" Google using open tools such as [Plausible](https://plausible.io/), " +"[Cloudflare Web Analytics](https://www.cloudflare.com/web-analytics/) and" +" [Matomo](https://matomo.org) for web analytics." +msgstr "" + +#: ../../documentation/hosting-tools/website-hosting-optimizing-your-docs.md:13 +msgid "" +"pyOpenSci is currently looking into free options for open source " +"developers." +msgstr "" + +#: ../../documentation/hosting-tools/website-hosting-optimizing-your-docs.md:16 +msgid "" +"Some of the [sphinx themes such as the `pydata-sphinx-theme` and sphinx-" +"book-theme have built in support for Google Analytics](https://pydata-" +"sphinx-theme.readthedocs.io/en/latest/user_guide/analytics.html#google-" +"analytics). However, if the theme that you chose does not offer Google " +"Analytics support, you can use the [`sphinxcontrib-gtagjs` " +"extension](https://github.com/attakei/sphinxcontrib-gtagjs). This " +"extension will add a Google Analytics site tag to each page of your " +"documentation." +msgstr "" + +#: ../../documentation/hosting-tools/website-hosting-optimizing-your-docs.md:22 +msgid "" +"[sphinx-sitemap](https://sphinx-" +"sitemap.readthedocs.io/en/latest/index.html) for search engine " +"optimization" +msgstr "" + +#: ../../documentation/hosting-tools/website-hosting-optimizing-your-docs.md:24 +msgid "" +"While we are trying to move away from Google Analytics do to compliance " +"and privacy issues, search engine optimization is still important. Google" +" is the most popular search engine. And if your documentation is search " +"optimized, users are more likely to find your package!" +msgstr "" + +#: ../../documentation/hosting-tools/website-hosting-optimizing-your-docs.md:30 +msgid "" +"If you are interested in optimizing your documentation for search engines" +" such as Google, you want a **sitemap.xml** file. You can submit this " +"sitemap to Google and it will index your entire site. This over time can " +"make the content on your site more visible to others when they search." +msgstr "" + +#: ../../documentation/hosting-tools/website-hosting-optimizing-your-docs.md:36 +msgid "This extension is lightweight." +msgstr "" + +#: ../../documentation/hosting-tools/website-hosting-optimizing-your-docs.md:38 +msgid "" +"It [requires that you to add it to your Sphinx `conf.py` extension list " +"and site your documentation base url](https://sphinx-" +"sitemap.readthedocs.io/en/latest/getting-started.html)." +msgstr "" + +#: ../../documentation/hosting-tools/website-hosting-optimizing-your-docs.md:40 +msgid "[sphinxext.opengraph](https://github.com/wpilibsuite/sphinxext-opengraph)" +msgstr "" + +#: ../../documentation/hosting-tools/website-hosting-optimizing-your-docs.md:42 +msgid "" +"OpenGraph is an extension that allows you to add metadata to your " +"documentation content pages. [The OpenGraph protocol allows other " +"websites to provide a useful preview of the content on your page when " +"shared](https://www.freecodecamp.org/news/what-is-open-graph-and-how-" +"can-i-use-it-for-my-website/#what-is-open-graph). This is important for " +"when the pages in your documentation are shared on social media sites " +"like Twitter and Mastodon and even for shares on tools like Slack and " +"Discourse." +msgstr "" + +#: ../../documentation/index.md:3 +msgid "Documentation Overview" +msgstr "" + +#: ../../documentation/index.md:3 ../../documentation/index.md:10 +#: ../../documentation/index.md:21 ../../documentation/index.md:42 +msgid "Intro" +msgstr "" + +#: ../../documentation/index.md:10 +msgid "Create Your Docs" +msgstr "" + +#: ../../documentation/index.md:10 +msgid "Document Your Code (API)" +msgstr "" + +#: ../../documentation/index.md:10 +msgid "Create Package Tutorials" +msgstr "" + +#: ../../documentation/index.md:10 +msgid "Write User Documentation" +msgstr "" + +#: ../../documentation/index.md:21 +msgid "Contributing File" +msgstr "" + +#: ../../documentation/index.md:21 +msgid "Development Guide" +msgstr "" + +#: ../../documentation/index.md:21 +msgid "Changelog File" +msgstr "" + +#: ../../documentation/index.md:21 +msgid "Docs for Contributors & Maintainers" +msgstr "" + +#: ../../documentation/index.md:32 +msgid "README file" +msgstr "" + +#: ../../documentation/index.md:32 +msgid "Code of Conduct File" +msgstr "" + +#: ../../documentation/index.md:32 +msgid "LICENSE files" +msgstr "" + +#: ../../documentation/index.md:32 +msgid "Community Docs" +msgstr "" + +#: ../../documentation/index.md:42 +msgid "Sphinx for Docs" +msgstr "" + +#: ../../documentation/index.md:42 +msgid "myST vs Markdown vs rst" +msgstr "" + +#: ../../documentation/index.md:42 +msgid "Publish Your Docs" +msgstr "" + +#: ../../documentation/index.md:42 +msgid "Website Hosting and Optimization" +msgstr "" + +#: ../../documentation/index.md:42 +msgid "Publication tools for your docs" +msgstr "" + +#: ../../documentation/index.md:1 +msgid "Documentation for your Open Source Python Package" +msgstr "" + +#: ../../documentation/index.md:55 +msgid "" +"Please note that the tools discussed here are those that we see commonly " +"used in the community. As tools evolve we will update this guide. If you " +"are submitting a package for pyOpenSci peer review and use other tools " +"that are not listed in our guide to build your package you can still " +"submit for review! The tools listed here are suggestions, not " +"requirements. Our requirements are focused on the documentation content " +"of your package." +msgstr "" + +#: ../../documentation/index.md:65 +msgid "Documentation is critical for your Python package's success" +msgstr "" + +#: ../../documentation/index.md:67 +msgid "" +"Documentation is as important to the success of your Python open source " +"package as the code itself." +msgstr "" + +#: ../../documentation/index.md:70 +msgid "" +"Quality code is of course valuable as its how your package gets the tasks" +" done. However, if users don't understand how to use your package in " +"their workflows, then they won't use it." +msgstr "" + +#: ../../documentation/index.md:73 +msgid "" +"Further, explicitly documenting how to contribute is important if you " +"wish to build a base of contributors to your package." +msgstr "" + +#: ../../documentation/index.md:76 +msgid "Two types of Python package users" +msgstr "" + +#: ../../documentation/index.md:78 +msgid "" +"The documentation that you write for your package should target two types" +" of users:" +msgstr "" + +#: ../../documentation/index.md:81 +msgid "1. Basic Tool Users" +msgstr "" + +#: ../../documentation/index.md:83 +msgid "" +"Basic tool users are the people who will use your package code in their " +"Python workflows. They might be new(er) to Python and/or data science. Or" +" expert programmers. But they might not have a background in software " +"development. These users need to know:" +msgstr "" + +#: ../../documentation/index.md:88 +msgid "How to install your package" +msgstr "" + +#: ../../documentation/index.md:89 +msgid "How to install dependencies that your package requires" +msgstr "" + +#: ../../documentation/index.md:90 +msgid "How to get started using the code base" +msgstr "" + +#: ../../documentation/index.md:91 +msgid "" +"Information on how to cite your code / give you credit if they are using " +"it in a research application." +msgstr "" + +#: ../../documentation/index.md:93 +msgid "" +"Information on the license that your code uses so they know how they can " +"or can't use the code in an operational setting." +msgstr "" + +#: ../../documentation/index.md:96 +msgid "2. Potential tool contributors" +msgstr "" + +#: ../../documentation/index.md:98 +msgid "" +"The other subset of users are more experienced and/or more engaged with " +"your package. As such they are potential contributors. These users:" +msgstr "" + +#: ../../documentation/index.md:102 +msgid "might have a software development background," +msgstr "" + +#: ../../documentation/index.md:103 +msgid "" +"might also be able to contribute bug fixes to your package or updates to " +"your documentation" +msgstr "" + +#: ../../documentation/index.md:104 +msgid "" +"might also just be users who will find spelling errors in your " +"documentation, or bugs in your tutorials." +msgstr "" + +#: ../../documentation/index.md:106 +msgid "" +"These users need all of the things that a basic user needs. But, they " +"also need to understand how you'd like for them to contribute to your " +"package. These potential contributors need:" +msgstr "" + +#: ../../documentation/index.md:110 +msgid "" +"A development guide to help them understand the infrastructure used in " +"your package repository." +msgstr "" + +#: ../../documentation/index.md:111 +msgid "" +"Contributing guidelines that clarify the types of contributions that you " +"welcome and how you'd prefer those contributions to be submitted." +msgstr "" + +#: ../../documentation/index.md:114 +msgid "" +"It's important to remember that the definition of what a contribution is " +"can be broad. A contribution could be something as simple as a bug " +"report. Or fixing a spelling issue in your documentation. Or it could be " +"a code fix that includes a new test that covers an edge-case that they " +"discovered." +msgstr "" + +#: ../../documentation/index.md:120 +msgid "Documentation elements that pyOpenSci looks for reviewing a Python package" +msgstr "" + +#: ../../documentation/index.md:122 +msgid "" +"In the pyOpenSci open peer review, we look for a documentation structure " +"that supports both your tool users and potential contributors. The files " +"and elements that we look for specifically can be found in our peer " +"review check list (see link below)." +msgstr "" + +#: ../../documentation/index.md:127 +msgid "" +"In this guide, we discuss each required element, and also discuss other " +"elements that you should consider in your package's documentation in more" +" detail." +msgstr "" + +#: ../../documentation/index.md:131 +msgid "View pyOpenSci peer review check list" +msgstr "" + +#: ../../documentation/index.md:138 +msgid "" +"Image showing the files in the the MovingPandas GitHub repository. Files " +"in the image include code of conduct.md contributing.md license.txt and " +"readme.md." +msgstr "" + +#: ../../documentation/index.md:144 +msgid "" +"An example from the MovingPandas GitHub repository with all of the major " +"files in it including CONTRIBUTING.md, README.md, CODE_OF_CONDUCT.md and " +"a LICENSE.txt file. *(screen shot taken Nov 23 2022)*" +msgstr "" + +#: ../../documentation/index.md:147 +msgid "What's next in this Python package documentation section?" +msgstr "" + +#: ../../documentation/index.md:149 +msgid "" +"In this section of the pyOpenSci package guide, we will walk you through " +"best practices for setting up documentation for your Python package. We " +"will also suggest tools that you can use to build your user-facing " +"documentation website." +msgstr "" + +#: ../../documentation/index.md:154 +msgid "Todo" +msgstr "" + +#: ../../documentation/index.md:156 +msgid "" +"Python version support You should always be explicit about which versions" +" of Python your package supports. Keeping compatibility with old Python " +"versions can be difficult as functionality changes. A good rule of thumb " +"is that the package should support, at least, the latest three Python " +"versions (e.g., 3.8, 3.7, 3.6)." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:1 +msgid "CHANGELOG.md Guide" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:3 +msgid "Introduction" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:5 +msgid "" +"The `CHANGELOG.md` document serves as a valuable resource for developers " +"and users alike to track the evolution of a project over time. " +"Understanding the structure and purpose of a changelog helps users and " +"contributors stay informed about new features, bug fixes, and other " +"changes introduced in each release." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:7 +msgid "What is CHANGELOG.md?" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:9 +msgid "" +"The primary purpose of `CHANGELOG.md` is to provide a record of notable " +"changes made to the project with each new release. This document helps " +"users understand what has been added, fixed, modified, or removed with " +"each version of the software." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:11 +msgid "" +"[Keep a CHAGELOG.md](https://keepachangelog.com/en/1.1.0/) is a great, " +"simple resource for understanding what a changelog is and how to create a" +" good changelog. It also includes examples of things to avoid." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:13 +msgid "Versioning your Python package and semantic versioning" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:16 +msgid "" +"An important component of a package that serves as the backbone behind " +"the changelog file is a good versioning scheme. Semantic Versioning is " +"widely used across Python packages." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:17 +msgid "" +"[Creating New Versions of Your Python Package](../../package-structure-" +"code/python-package-versions.md)" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:18 +msgid "[Semantic Versioning](https://semver.org)" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:21 +msgid "Why is it important?" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:23 +msgid "" +"A well-maintained changelog is essential for transparent communication " +"with users and developers. It serves as a centralized hub for documenting" +" changes and highlights the progress made in each release. By keeping the" +" changelog up-to-date, project maintainers can build trust with their " +"user base and demonstrate their commitment to improving the software." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:25 +msgid "What does it include?" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:27 +msgid "" +"The contents of a changelog.md file typically follow a structured format," +" detailing the changes introduced in each release. While the exact format" +" may vary depending on the project's conventions, some common elements " +"found in changelogs for Python packages include:" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:29 +msgid "" +"**Versioning**: Clear identification of each release version using " +"semantic versioning or another versioning scheme adopted by the project." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:31 +msgid "" +"**Release Date**: The date when each version was released to the public, " +"providing context for the timeline of changes." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:33 +msgid "" +"**Change Categories**: Organizing changes into categories such as " +"\"Added,\" \"Changed,\" \"Fixed,\" and \"Removed\" to facilitate " +"navigation and understanding." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:35 +msgid "" +"**Description of Changes**: A concise description of the changes made in " +"each category, including new features, enhancements, bug fixes, and " +"deprecated functionality." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:37 +msgid "" +"**Links to Issues or Pull Requests**: References to relevant issue " +"tracker items or pull requests associated with each change, enabling " +"users to access more detailed information if needed." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:39 +msgid "" +"**Upgrade Instructions**: Guidance for users on how to upgrade to the " +"latest version, including any breaking changes or migration steps they " +"need to be aware of." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:41 +msgid "" +"**Contributor Recognition**: Acknowledgment of contributors who made " +"significant contributions to the release, fostering a sense of community " +"and appreciation for their efforts." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:43 +msgid "How do maintainers use it?" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:45 +msgid "Often you will see a changelog that documents a few things:" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:47 +msgid "Unreleased Section" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:49 +msgid "" +"Unreleased commits are at the top of the changelog, commonly in an " +"`Unreleased` section. This is where you can add new fixes, updates and " +"features that have been added to the package since the last release." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:51 +msgid "This section might look something like this:" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:59 +msgid "Release Sections" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:61 +msgid "" +"When you are ready to make a new release, you can move the elements into " +"a section that is specific to that new release number." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:63 +msgid "" +"This specific release section will sit below the unreleased section and " +"can include any updates, additions, deprecations and contributors." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:65 +msgid "" +"The unreleased section then always lives at the top of the file and new " +"features continue to be added there. At the same time, after releasing a " +"version like v1.0 all of its features remain in that specific section." +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:83 +msgid "What does it look like?" +msgstr "" + +#: ../../documentation/repository-files/changelog-file.md:85 +msgid "" +"This example comes from [Devicely](https://github.com/hpi-" +"dhc/devicely/blob/main/CHANGELOG.md), a pyOpenSci accepted package." +msgstr "" + +#: ../../documentation/repository-files/code-of-conduct-file.md:1 +msgid "The CODE_OF_CONDUCT file - Python Packaging" +msgstr "" + +#: ../../documentation/repository-files/code-of-conduct-file.md:3 +msgid "Example CODE_OF_CONDUCT files" +msgstr "" + +#: ../../documentation/repository-files/code-of-conduct-file.md:6 +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:7 +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:10 +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:16 +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:20 +msgid "Why you need a CODE_OF_CONDUCT" +msgstr "" + +#: ../../documentation/repository-files/code-of-conduct-file.md:22 +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:26 +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:32 +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:1 +msgid "Contributing File in your Python Open Source Package" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:3 +msgid "What a CONTRIBUTING.md file should contain" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:5 +msgid "Example contributing files" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:8 +msgid "" +"[pyGMT contributing " +"file](https://github.com/GenericMappingTools/pygmt/blob/main/CONTRIBUTING.md)" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:9 +msgid "" +"[fatiando verde's contributing " +"file](https://github.com/fatiando/verde/blob/main/CONTRIBUTING.md)" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:12 +msgid "" +"Your Python open source package should include a file called " +"**CONTRIBUTING.md** located in the root of your repository (with your " +"**README.md** file)." +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:15 +msgid "" +"The contributing file should include information about the types of " +"contributions that you welcome, and how you'd like to see contributions " +"happen." +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:19 +msgid "" +"This guide should also include information for someone interested in " +"asking questions, submitting issues or pull requests. It should have " +"things like:" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:22 +msgid "" +"Any guidelines that you have in place for users submitting issues, pull " +"requests or asking questions." +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:23 +msgid "A link to your code of conduct" +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:24 +msgid "A link to licensing information found in your README file." +msgstr "" + +#: ../../documentation/repository-files/contributing-file.md:25 +msgid "A link to a development guide if you have one" +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:1 +msgid "What the development guide for your Python package should contain" +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:3 +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:7 +msgid "Set up a development environment locally to work on your package" +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:8 +msgid "Run the test suite" +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:9 +msgid "Build documentation locally" +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:11 +msgid "The development guide should also have guidelines for:" +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:12 +msgid "" +"code standards including docstring style, code format and any specific " +"code approaches that the package follows." +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:14 +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:16 +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:18 +msgid "Why a development guide is important" +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:20 +msgid "It's valuable to have a development guide, in the case that you wish to:" +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:23 +msgid "Onboard new maintainers." +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:24 +msgid "" +"Allow technically inclined contributors to make thoughtful and useful " +"code based pull requests to your repository." +msgstr "" + +#: ../../documentation/repository-files/development-guide.md:26 +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:31 +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:36 +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:43 +msgid "" +"[The Mozilla Science Lab website has a nice outline of things to consider" +" when creating a contributing guide](https://mozillascience.github.io" +"/working-open-workshop/contributing/)" +msgstr "" + +#: ../../documentation/repository-files/intro.md:1 +msgid "Documentation Files That Should be in your Python Package Repository" +msgstr "" + +#: ../../documentation/repository-files/intro.md:3 +msgid "" +"In this section of the Python packaging guide, we review all of the files" +" that you should have in your Python package repository. Your Python " +"package should, at a minimum have the following files:" +msgstr "" + +#: ../../documentation/repository-files/intro.md:7 +msgid "" +"The files mentions above (README, Code of Conduct, license file, etc) are" +" used as a measure of package community health on many online platforms. " +"Below, you can see an example how Github evaluates community health. This" +" community health link is available for all GitHub repositories." +msgstr "" + +#: ../../documentation/repository-files/intro.md:13 +msgid "" +"Image showing that the MovingPandas GitHub repository community health " +"page with green checks next to each file including a description, README," +" code of conduct, contributing, license and issue templates. Note that " +"Security policy has a yellow circle next to it as that is missing from " +"the repo." +msgstr "" + +#: ../../documentation/repository-files/intro.md:19 +msgid "" +"GitHub community health looks for a readme file among other elements when" +" it evaluates the community level health of your repository. This example" +" is from the [MovingPandas GitHub " +"repo](https://github.com/anitagraser/movingpandas/community) *(screen " +"shot taken Nov 23 2022)*" +msgstr "" + +#: ../../documentation/repository-files/intro.md:22 +msgid "" +"[Snyk](https://snyk.io/advisor/python) is another well-known company that" +" keeps tabs on package health. Below you can see a similar evaluation of " +"files in the Github repo as a measure of community health." +msgstr "" + +#: ../../documentation/repository-files/intro.md:26 +msgid "" +"Screenshot of the Snyk page for movingpandas. It shows that the " +"repository has a README file, contributing file, code of conduct. It also" +" shows that it has 30 contributors and no funding. The package health " +"score is 78/100." +msgstr "" + +#: ../../documentation/repository-files/intro.md:32 +msgid "" +"Screenshot showing [SNYK](https://snyk.io/advisor/python/movingpandas) " +"package health for moving pandas. Notice both platforms look for a README" +" file. *(screen shot taken Nov 23 2022)*" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:1 +msgid "License files for scientific Python open source software" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:3 +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:10 +msgid "What is a Open Source License file?" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:12 +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:16 +msgid "Why licenses are important" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:18 +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:20 +msgid "How they can use your software" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:21 +msgid "Whether the software can be reused or adapted for other purposes" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:22 +msgid "How people can contribute to your project" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:24 +msgid "and more." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:26 +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:29 +msgid "Where to store your license" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:31 +msgid "" +"Your `LICENSE` file should be stored at root of your GitHub / GitLab " +"repository." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:33 +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:36 +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:38 +msgid "Use open permissive licenses when possible" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:40 +msgid "" +"We generally suggest that you use a permissive, license that is [Open " +"Software Initiative (OSI) approved](https://opensource.org/licenses/). If" +" you are [submitting your package to pyOpenSci for peer " +"review](https://www.pyopensci.org/about-peer-review/index.html), then we " +"require an OSI approved license." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:44 +msgid "How to choose a license" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:46 +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:49 +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:54 +msgid "License recommendations from the SciPy package" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:55 +msgid "" +"[The SciPy documentation has an excellent overview of " +"licenses.](https://docs.scipy.org/doc/scipy/dev/core-" +"dev/index.html#licensing). Once of the key elements that these docs " +"recommend is ensuring that the license that you select is complementary " +"to license used in the core 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:61 +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:63 +msgid "" +"To coordinate with other packages in our 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:69 +msgid "" +"Important: make sure that you closely follow the guidelines outlines by " +"the License that you chose" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:71 +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:74 +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:78 +msgid "An example of how a license determine how code can be reused" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:81 +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:83 +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 StackOverflow." +msgstr "" + +#: ../../documentation/repository-files/license-files.md:85 +msgid "" +"This means that technically, if you copy code from the Stack Overflow " +"website, and use it in your package. And your packages uses a different " +"license such as a MIT license, you are violating Stack Overflow's license" +" requirements!" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:87 +msgid "🚨 Proceed with caution! 🚨" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:91 +msgid "What about software citation?" +msgstr "" + +#: ../../documentation/repository-files/license-files.md:93 +msgid "" +"While many permissive licenses do not require citation we STRONG " +"encourage that you cite all software that you use in papers, blogs and " +"other publications. You tell your users how to cite your package by using" +" a [citation.cff file](https://docs.github.com/en/repositories/managing-" +"your-repositorys-settings-and-features/customizing-your-repository/about-" +"citation-files). We will cover this topic when we talk about creating " +"DOI's for your package using zenodo." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:1 +msgid "README File Guidelines and Resources" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:3 +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:7 +msgid "The README.md file is the landing page of:" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:9 +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:10 +msgid "Your package's GitHub repository" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:12 +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:14 +msgid "" +"[GitHub community health for MovingPandas (available for all " +"repositories)](https://github.com/anitagraser/movingpandas/community) and" +" [Snyk - moving pandas " +"example](https://snyk.io/advisor/python/movingpandas)" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:17 +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:23 +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:26 +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:30 +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:33 +msgid "Please go through this list before submitting your package to pyOpenSci" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:50 +msgid "What your README.md file should contain" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:52 +msgid "" +"Your **README.md** file should contain the following things (listed from " +"top to bottom):" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:54 +msgid "✔️ Your package's name" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:55 +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:58 +msgid "" +"✔️ Badges for current package version, continuous integration and test " +"coverage" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:60 +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:66 +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:69 +msgid "Some badges that you might consider adding to your README file include:" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:71 +msgid "Current version of the package on PyPI / Anaconda.org" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:73 +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:73 +msgid "PyPI version shields.io" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:75 +msgid "" +"Status of tests (pass or fail) - Example: [![CI Build](https://github.com" +"/pandera-" +"dev/pandera/workflows/CI%20Tests/badge.svg?branch=main)](https://github.com" +"/pandera-" +"dev/pandera/actions?query=workflow%3A%22CI+Tests%22+branch%3Amain)" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:75 +msgid "CI Build" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:77 +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:77 +msgid "Docs Building" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:79 +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:79 +msgid "DOI" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:82 +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://tinyurl.com/y22nb8up)](https://github.com/pyOpenSci" +"/software-review/issues/12)" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:82 +msgid "pyOpenSci" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:90 +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:93 +msgid "✔️ A short, easy-to-understand description of what your package does" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:95 +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:101 +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:106 +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:110 +msgid "" +"The goal of this description is to maximize accessibility of your " +"**README** file." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:114 +msgid "✔️ Installation instructions" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:116 +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:119 +msgid "✔️ Document any additional setup required" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:121 +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:126 +msgid "✔️ Brief demonstration of how to use the package" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:128 +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:131 +msgid "✔️ Descriptive links to package documentation, short tutorials" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:133 +msgid "Include descriptive links to:" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:135 +msgid "The package's documentation page." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:136 +msgid "Short tutorials that demonstrate application of your package." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:138 +msgid "Too Much Of A Good Thing" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:141 +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:143 +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:149 +msgid "✔️ A Community Section with Links to Contributing Guide, Code of Conduct" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:151 +msgid "Use your README.md file to direct users to more information on:" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:153 +msgid "Contributing to your package" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:154 +msgid "Development setup for more advanced technical contributors" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:155 +msgid "Your code of conduct" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:156 +msgid "Licensing information" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:158 +msgid "" +"All of the above files are important for building community around your " +"project." +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:161 +msgid "✔️ Citation information" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:163 +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:167 +msgid "README Resources" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:171 +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:174 +msgid "" +"[How to Write a Great README - Bane " +"Sullivan](https://github.com/banesullivan/README)" +msgstr "" + +#: ../../documentation/repository-files/readme-file-best-practices.md:175 +msgid "" +"[Art of README - Kira (@hackergrrl)](https://github.com/hackergrrl/art-" +"of-readme)" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:1 +msgid "Create tutorials in your Python package documentation" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:6 +msgid "" +"Your package should have tutorials that make it easy for a user to get " +"started using your package. Ideally, those tutorials also can be run from" +" start to finish providing a second set of checks (on top of your test " +"suite) to your package's code base." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:11 +msgid "" +"On this page, we review two Sphinx extensions (`sphinx-gallery` and " +"`nbsphinx`) that allow you to create reproducible tutorials that are run" +" when your Sphinx documentation builds." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:15 +msgid "Create Python package tutorials that run when you build your docs" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:17 +msgid "" +"Adding well constructed tutorials to your package will make it easier for" +" someone new to begin using your package." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:20 +msgid "" +"There are two Sphinx tools that make it easy to add tutorials to your " +"package:" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:22 +msgid "[Sphinx Gallery](https://sphinx-gallery.github.io/stable/index.html) and" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:23 +msgid "[NbSphinx](https://nbsphinx.readthedocs.io/en/latest/)" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:25 +msgid "Both of these tools act as Sphinx extensions and:" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:27 +msgid "" +"Support creating a gallery type page in your Sphinx documentation where " +"users can explore tutorials via thumbnails." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:28 +msgid "" +"Run the code in your tutorials adding another level of \"testing\" for " +"your package as used." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:29 +msgid "Render your tutorials with Python code and plot outputs" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:31 +msgid "[sphinx gallery:](https://sphinx-gallery.github.io/stable/index.html)" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:33 +msgid "" +"If you prefer to write your tutorials using Python **.py** scripts, you " +"may enjoy using Sphinx gallery. Sphinx gallery uses **.py** files with " +"text and code sections that mimic the Jupyter Notebook format. When you " +"build your documentation, the gallery extension:" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:38 +msgid "" +"Runs the code in each tutorial. Running your tutorial like this acts as a" +" check to ensure your package's functions, classes, methods, and " +"attributes (ie the API) are working as they should." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:39 +msgid "" +"Creates a downloadable Jupyter Notebook **.ipynb** file and a **.py** " +"script for your tutorial that a user can quickly download and run." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:40 +msgid "" +"Creates a rendered **.html** page with the code elements and code " +"outputs in a user-friendly tutorial gallery." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:41 +msgid "" +"Creates a gallery landing page with visual thumbnails for each tutorial " +"that you create." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:44 +msgid "" +"Image showing the gallery output provided by sphinx-gallery where each " +"tutorial is in a grid and the tutorial thumbnails are created from a " +"graphic in the tutorial." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:50 +msgid "" +"`sphinx-gallery` makes it easy to create a user-friendly tutorial " +"gallery. Each tutorial has a download link where the user can download a " +"**.py** file or a Jupyter Notebook. And it renders the tutorials in a " +"user-friendly grid." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:54 +msgid "Below you can see what a tutorial looks like created with sphinx-gallery." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:56 +msgid "" +"Image showing ta single tutorial from Sphinx gallery. The tutorial shows " +"a simple matplotlib created plot and associated code." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:62 +msgid "" +"`sphinx-gallery` tutorials by default include download links for both the" +" python script (**.py** file) and a Jupyter notebook (**.ipynb** file) at" +" the bottom." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:66 +msgid "Sphinx Gallery benefits" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:67 +msgid "easy-to-download notebook and .py outputs for each tutorials." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:68 +msgid ".py files are easy to work with in the GitHub pull request environment." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:69 +msgid "Nice gridded gallery output." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:70 +msgid "" +"Build execution time data per tutorial. [Example](https://sphinx-" +"gallery.github.io/stable/auto_examples/sg_execution_times.html)" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:72 +msgid "Sphinx gallery challenges" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:74 +msgid "The downsides of using Sphinx gallery include:" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:76 +msgid "" +"the **.py** files can be finicky to configure, particularly if you have " +"matplotlib plot outputs." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:78 +msgid "" +"For example: To allow for plots to render, you need to name each file " +"with `plot_` at the beginning." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:81 +msgid "" +"Many users these days are used to working in Jupyter Notebooks. .py may " +"be slightly less user friendly to work with" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:83 +msgid "" +"These nuances can make it challenging for potential contributors to add " +"tutorials to your package. This can also present maintenance challenge." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:86 +msgid "Add about the gallery setup:" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:93 +msgid "File directory structure:" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:114 +msgid "" +"[nbsphinx - tutorials using Jupyter " +"Notebooks](https://nbsphinx.readthedocs.io/en/latest/)" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:116 +msgid "" +"If you prefer to use Jupyter Notebooks to create tutorials you can use " +"nbsphinx. nbsphinx operates similarly to Sphinx gallery in that:" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:119 +msgid "It runs your notebooks and produces outputs in the rendered tutorials" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:121 +msgid "" +"Pro/con By default it does not support downloading of **.py** and " +"**.ipynb** files. However you can add a [link to the notebook at the top " +"of the page with some additional conf.py settings (see: epilog " +"settings)](https://nbsphinx.readthedocs.io/en/0.8.10/prolog-and-" +"epilog.html)" +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:125 +msgid "" +"Image showing the gallery output provided by nbsphinx using the sphinx-" +"gallery front end interface." +msgstr "" + +#: ../../documentation/write-user-documentation/create-package-tutorials.md:131 +msgid "" +"`nbsphinx` can be combined with Sphinx gallery to create a gallery of " +"tutorials. However, rather than rendering the gallery as a grid, it lists" +" all of the gallery elements in a single column." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:1 +msgid "Document the code in your package's API using docstrings" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:3 +msgid "What is an API?" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:5 +msgid "" +"API stands for **A**pplied **P**rogramming **I**nterface. When discussed " +"in the context of a (Python) package, the API refers to the functions, " +"classes, methods, and attributes that a package maintainer creates for " +"users." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:9 +msgid "" +"A simple example of a package API element: For instance, a package might " +"have a function called `add_numbers()` that adds up a bunch of numbers. " +"To add up numbers, you as the user simply call `add_numbers(1,2,3)` and " +"the package function calculates the value and returns `6`. By calling the" +" `add_numbers` function, you are using the package's API." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:15 +msgid "" +"Package APIs consist of functions, classes, methods and attributes that " +"create a user interface." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:17 +msgid "What is a docstring and how does it relate to documentation?" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:19 +msgid "" +"In Python, a docstring refers to text in a function, method or class that" +" describes what the function does and its inputs and outputs. Python " +"programmers usually refer to the inputs to functions as " +"[\"parameters\"](https://docs.python.org/3/glossary.html#term-parameter) " +"or [\"arguments\"](https://docs.python.org/3/faq/programming.html#faq-" +"argument-vs-parameter), and the outputs are often called \"return " +"values\"" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:22 +msgid "The docstring is thus important for:" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:24 +msgid "" +"When you call `help()` in Python, for example, `help(add_numbers)` will " +"show the text of the function's docstring. The docstring thus helps a " +"user better understand how to apply the function more effectively to " +"their workflow." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:25 +msgid "" +"When you build your package's documentation, the docstrings can also be " +"used to automatically create full API documentation that provides a clean" +" view of all its functions, classes, methods, and attributes." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:28 +msgid "" +"Example API Documentation for all functions, classes, methods, and " +"attributes in a package." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:29 +msgid "" +"[View example high-level API documentation for the Verde package. This " +"page lists every function and class in the package along with a brief " +"explanation of what it " +"does](https://www.fatiando.org/verde/latest/api/index.html)" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:30 +msgid "" +"[You can further dig down to see what a specific function does within the" +" package by clicking on an API " +"element](https://www.fatiando.org/verde/latest/api/generated/verde.grid_coordinates.html#verde.grid_coordinates)" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:33 +msgid "Python package API documentation" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:35 +msgid "" +"If you have a descriptive docstring for every user-facing class, method, " +"attribute and/or function in your package (_within reason_), then your " +"package's API is considered well-documented." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:38 +msgid "" +"In Python, this means that you need to add a docstring for every user-" +"facing class, method, attribute and/or function in your package (_within " +"reason_) that:" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:42 +msgid "Explains what the function, method, attribute, or class does" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:43 +msgid "Defines the `type` inputs and outputs (ie. `string`, `int`, `np.array`)" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:44 +msgid "Explains the expected output `return` of the object, method or function." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:47 +msgid "Three Python docstring formats and why we like NumPy style" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:49 +msgid "" +"There are several Python docstring formats that you can choose to use " +"when documenting your package including:" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:52 +msgid "" +"[NumPy-style](https://numpydoc.readthedocs.io/en/latest/format.html" +"#docstring-standard)" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:53 +msgid "" +"[google style](https://sphinxcontrib-" +"napoleon.readthedocs.io/en/latest/example_google.html)" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:54 +msgid "" +"[reST style](https://sphinx-rtd-" +"tutorial.readthedocs.io/en/latest/docstrings.html)" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:58 +msgid "" +"We suggest using [NumPy-style " +"docstrings](https://numpydoc.readthedocs.io/en/latest/format.html" +"#docstring-standard) for your Python documentation because:" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:61 +msgid "" +"NumPy style docstrings are core to the scientific Python ecosystem and " +"defined in the [NumPy style " +"guide](https://numpydoc.readthedocs.io/en/latest/format.html). Thus you " +"will find them widely used there." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:62 +msgid "" +"The Numpy style docstring is simplified and thus easier to read both in " +"the code and when calling `help()` in Python. In contrast, some feel that" +" reST style docstrings are harder to quickly scan, and can take up more " +"lines of code in modules." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:65 +msgid "" +"If you are using NumPy style docstrings, be sure to include the [sphinx " +"napoleon extension](https://www.sphinx-" +"doc.org/en/master/usage/extensions/napoleon.html) in your documentation " +"`conf.py` file. This extension allows Sphinx to properly read and format " +"NumPy format docstrings." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:70 +msgid "Docstring examples Better and Best" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:72 +msgid "" +"Below is a good example of a well-documented function. Notice that this " +"function's docstring describes the function's inputs and the function's " +"output (or return value). The initial description of the function is " +"short (one line). Following that single-line description, there is a " +"slightly longer description of what the function does (2 to 3 sentences)." +" The return of the function is also specified." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:106 +msgid "Best: a docstring with example use of the function" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:108 +msgid "" +"This example contains an example of using the function that is also " +"tested in sphinx using " +"[doctest](https://docs.python.org/3/library/doctest.html)." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:159 +msgid "" +"Using the above NumPy format docstring in sphinx, the autodoc extension " +"will create the about documentation section for the `extent_to_json` " +"function. The output of the `es.extent_to_json(rmnp)` command can even be" +" tested using doctest adding another quality check to your package." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:165 +msgid "" +"Using doctest to run docstring examples in your package's methods and " +"functions" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:170 +msgid "" +"Above, we provided some examples of good, better, best docstring formats." +" If you are using Sphinx to create your docs, you can add the " +"[doctest](https://www.sphinx-" +"doc.org/en/master/usage/extensions/doctest.html) extension to your Sphinx" +" build. Doctest provides an additional check for docstrings with example " +"code in them. Doctest runs the example code in your docstring `Examples` " +"checking that the expected output is correct. Similar to running " +"tutorials in your documentation, `doctest` can be a useful step that " +"assures that your package's code (API) runs as you expect it to." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:177 +msgid "" +"It's important to keep in mind that examples in your docstrings help " +"users using your package. Running `doctest` on those examples provides a " +"check of your package's API. doctest ensures that the functions and " +"methods in your package run as you expect them to. Neither of these items" +" replace a separate, stand-alone test suite that is designed to test your" +" package's core functionality across operating systems and Python " +"versions." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:185 +msgid "" +"Below is an example of a docstring with an example. doctest will run the " +"example below and test that if you provide `add_me` with the values 1 and" +" 3 it will return 4." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:218 +msgid "Adding type hints to your docstrings" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:220 +msgid "" +"In the example above, you saw the use of numpy-style docstrings to " +"describe data types that are passed into functions as parameters or into " +"classes as attributes. In a numpy-style docstring you add those types in " +"the Parameters section of the docstring. Below you can see that the " +"parameter `num1` and `num2` should both be a Python `int` (integer) " +"value." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:235 +msgid "" +"Describing the expected data type that a function or method requires " +"helps users better understand how to call a function or method." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:238 +msgid "" +"Type-hints add another layer of type documentation to your code. Type-" +"hints make it easier for new developers, your future self or contributors" +" to get to know your code base quickly." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:242 +msgid "" +"Type hints are added to the definition of your function. In the example " +"below, the parameters aNum and aNum2 are defined as being type = int " +"(integer)." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:249 +msgid "" +"You can further describe the expected function output using `->`. Below " +"the output of the function is also an int." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:257 +msgid "Why use type hints" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:259 +msgid "Type hints:" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:261 +msgid "Make development and debugging faster," +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:262 +msgid "" +"Make it easier for a user to see the data format inputs and outputs of " +"methods and functions," +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:263 +msgid "" +"Support using static type checking tools such as [`mypy`](https://mypy-" +"lang.org/) which will check your code to ensure types are correct." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:265 +msgid "You should consider adding type hinting to your code if:" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:267 +msgid "Your package performs data processing," +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:268 +msgid "You use functions that require complex inputs" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:269 +msgid "" +"You want to lower the entrance barrier for new contributors to help you " +"with your code." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:271 +msgid "Beware of too much type hinting" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:274 +msgid "As you add type hints to your code consider that in some cases:" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:276 +msgid "" +"If you have a complex code base, type hints may make code more difficult " +"to read. This is especially true when a parameter’s input takes multiple " +"data types and you list each one." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:277 +msgid "" +"Writing type hints for simple scripts and functions that perform obvious " +"operations don't make sense." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:280 +msgid "Gradually adding type hints" +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:282 +msgid "" +"Adding type hints can take a lot of time. However, you can add type hints" +" incrementally as you work on your code." +msgstr "" + +#: ../../documentation/write-user-documentation/document-your-code-api-docstrings.md:286 +msgid "" +"Adding type hints is also a great task for new contributors. It will help" +" them get to know your package's code and structure better before digging" +" into more complex contributions." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:1 +msgid "Create User Facing Documentation for your Python Package" +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:14 +msgid "Core components of user-facing Python package documentation" +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:15 +msgid "Below we break documentation into two broad types." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:17 +msgid "" +"**User-facing documentation** refers to documentation that describes the " +"way the tools within a package are broadly used in workflows. **API " +"documentation** refers to documentation of functions, classes, methods, " +"and attributes in your code and is written at a more granular level. This" +" documentation is what a user sees when they type `help(function-name)`." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:23 +msgid "" +"Your user-facing documentation for your Python package should include " +"several core components." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:26 +msgid "" +"**Documentation Website:** This refers to easy-to-read documentation that" +" helps someone use your package. This documentation should help users " +"both install and use your package." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:27 +msgid "" +"**Short Tutorials:** Your user-facing documentation should also include " +"[**short tutorials** that showcase core features of your package](create-" +"package-tutorials)." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:28 +msgid "" +"**Package Code / API documentation:** You package's functions, classes, " +"methods, and attributes (the API) should also be documented. API " +"documentation can be generated from " +"[docstrings](https://pandas.pydata.org/docs/development/contributing_docstring.html)" +" found in your code. Ideally, you have docstrings for all user-facing " +"functions, classes, and methods in your Python package. [We discuss code " +"documentation and docstrings in greater detail here.](document-your-code-" +"api-docstrings)" +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:32 +msgid "Write usable documentation" +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:34 +msgid "" +"User-facing documentation should be published on a easy-to-navigate " +"website. The documentation should be written keeping in mind that users " +"may not be developers or expert-level programmers. Rather, the language " +"that you use in your documentation should not be highly technical." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:39 +msgid "" +"To make the language of your documentation more accessible to a broader " +"audience:" +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:42 +msgid "Whenever possible, define technical terms and jargon." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:43 +msgid "Consider writing instructions for a high-school level reader." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:44 +msgid "" +"Include step-by-step code examples, tutorials or vignettes that support " +"getting started using your package." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:46 +msgid "Four elements of a good open source documentation landing page" +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:48 +msgid "" +"To make it easy for users to find what they need quickly, consider adding" +" quick links on your package's landing page to the following elements:" +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:52 +msgid "" +"**Getting started:** This section should provide the user with a quick " +"start for installing your package. A small example of how to use the " +"package is good to have here as well. Or you can link to useful tutorials" +" in the get started section." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:53 +msgid "" +"**About:** Describe your project, stating its goals and its " +"functionality." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:54 +msgid "" +"**Community:** Instructions for how to help and/or get involved. This " +"might include links to your issues (if that is where you let users ask " +"questions) or the discussion part of your GitHub repo. This section might" +" include a development guide for those who might contribute to your " +"package." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:55 +msgid "" +"**API Documentation:** This is the detailed project documentation. Here " +"you store documentation for your package's API including all user-facing " +"functions, classes, methods, and attributes as well as any additional " +"high level discussion that will help people use your package." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:58 +msgid "" +"Image showing the landing page for GeoPandas documentation which has 4 " +"sections including Getting started, Documentation, About GeoPandas, " +"Community." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:64 +msgid "" +"The documentation landing page of GeoPandas, a spatial Python library, " +"has the 4 element specified above. Notice that the landing page is simple" +" and directs users to each element using a Sphinx card." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:67 +msgid "" +"NOTE: in many cases you can include your **README** file and your " +"**CONTRIBUTING** files in your documentation given those files may have " +"some of the components listed above." +msgstr "" + +#: ../../documentation/write-user-documentation/get-started.md:71 +msgid "" +"You can include files in Sphinx using the include directive. Below is an " +"example of doing this using `myst` syntax." +msgstr "" + +#: ../../documentation/write-user-documentation/intro.md:1 +msgid "Writing user-facing documentation for your Python package" +msgstr "" + +#: ../../documentation/write-user-documentation/intro.md:3 +msgid "" +"This section walks you through best practices for with writing " +"documentation for your Python package." +msgstr "" + +#: ../../documentation/write-user-documentation/intro.md:6 +msgid "" +"We talk about the elements that you should consider adding to your " +"documentation, the different types of users who might read your " +"documentation and how to create tutorials for your package." +msgstr "" + +#: ../../documentation/write-user-documentation/intro.md:10 +msgid "" +"Here we also cover sphinx extensions that you can user to make " +"documentation easier such as:" +msgstr "" + +#: ../../documentation/write-user-documentation/intro.md:13 +msgid "" +"autodoc to automagically populate documentation for your code's " +"functions, classes, methods and attributes (API documentation) and" +msgstr "" + +#: ../../documentation/write-user-documentation/intro.md:15 +msgid "sphinx gallery for tutorials." +msgstr "" diff --git a/locales/es/LC_MESSAGES/package-structure-code.po b/locales/es/LC_MESSAGES/package-structure-code.po new file mode 100644 index 00000000..90bc3f35 --- /dev/null +++ b/locales/es/LC_MESSAGES/package-structure-code.po @@ -0,0 +1,5301 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2024, pyOpenSci +# This file is distributed under the same license as the pyOpenSci Python +# Package Guide package. +# FIRST AUTHOR , 2024. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: pyOpenSci Python Package Guide \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-06-28 08:42-0400\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: es\n" +"Language-Team: es \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.15.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:38 +msgid "Use a code format tool (or tools) to make your life easier" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:40 +msgid "" +"We suggest that you use a code format tool, or a set of format tools, " +"because manually applying all of the PEP 8 format specifications is both " +"time consuming for maintainers and can be a road block for potential new " +"contributors. Code formatters will automagically reformat your code for " +"you, adhering to PEP 8 standards and applying consistent style decisions " +"throughout." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:46 +msgid "Setting up a code format suite of tools will:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:48 +msgid "Save you and your maintainer team time in fixing PEP 8 inconsistencies." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:49 +msgid "Ensure that format and style is consistent across your entire code-base." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:50 +msgid "" +"Avoid lengthy discussions with contributors and other maintainers about " +"personalized code format preferences during reviews." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:52 +msgid "" +"Avoid pure visual edits in the code base so that code reviews focus on " +"added value" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:54 +msgid "" +"Many packages use a suite of tools to apply code format rules, taking the" +" work out of manually implementing code format requirements." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:57 +msgid "" +"Consistent code format across packages within the (scientific) Python " +"ecosystem, will also broadly make code easier to scan, understand and " +"contribute to." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:60 +msgid "Linting vs format and style" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:62 +msgid "Before we dive in let's get a few definitions out of the way." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:64 +msgid "Code Linting" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:66 +msgid "" +"A code linter is a tool that will review your code and identify errors or" +" issues. A linter typically does not modify your code. It will tell you " +"what the error is and on what line it was discovered. Flake8, discussed " +"below, is an example of a commonly-used code linter." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:71 +msgid "Code Formatters (and stylers)" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:73 +msgid "" +"Code formatters will reformat your code for you. Python focused code " +"formatters often follow PEP 8 standards. However, they also make " +"stylistic decisions about code consistency." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:77 +msgid "" +"Black is an example of a commonly-used code formatter. Black both applies" +" PEP 8 standards while also making decisions about things like consistent" +" use of double quotes for strings, and spacing of items in lists." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:81 +msgid "You will learn more about Black below." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:83 +msgid "Code linting, formatting and styling tools" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:85 +msgid "Black" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:87 +msgid "" +"[Black](https://black.readthedocs.io/en/stable/) is a code formatter. " +"Black will automagically (and _unapologetically_) fix spacing issues and " +"ensure code format is consistent throughout your package. Black also " +"generally adheres to PEP 8 style guidelines with some exceptions. A few " +"examples of those exceptions are below:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:93 +msgid "" +"Black defaults to a line length of 88 (79 + 10%) rather than the 79 " +"character `PEP 8` specification. However, line length is a setting can be" +" manually overwritten in your Black configuration." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:94 +msgid "Black will not adjust line length in your comments or docstrings." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:95 +msgid "" +"This tool will not review and fix import order (you need `isort` or " +"`ruff` to do that - see below)." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:98 +msgid "" +"If you are interested in seeing how Black will format your code, you can " +"use the [Black playground](https://black.vercel.app/)" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:102 +msgid "" +"Using a code formatter like Black will leave you more time to work on " +"code function rather than worry about format." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:105 +msgid "Flake8" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:107 +msgid "" +"To adhere to Python `pep8` format standards, you might want to add " +"[flake8](https://flake8.pycqa.org/en/latest/) to your code format " +"toolbox." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:111 +msgid "flake8 will:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:113 +msgid "" +"Flag every line in your code that extends beyond 79 characters (including" +" those in docstrings and comments)" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:114 +msgid "" +"Flag spacing issues that conflict with PEP 8 guidelines such as missing " +"spaces after commas" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:116 +msgid "" +"Flake8 also flags unused imports and unused declared variables in your " +"modules." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:119 +msgid "" +"Below you can see the output of running `flake8 filename.py` at the " +"command line for a Python file within a package called `stravalib`." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:123 +msgid "The line length standard for PEP 8 is 79 characters." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:125 +msgid "" +"Notice that flake8 returns a list of issues that it found in the model.py" +" module on the command line. The Python file itself is not modified. " +"Using this output, you can fix each issue line by line manually." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:140 +msgid "Isort" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:142 +msgid "" +"Python imports refer to the Python packages that a module in your package" +" requires. Imports should always be located at the top of each Python " +"module in your package." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:146 +msgid "" +"[PEP 8 has specific standards for the order of these " +"imports](https://peps.python.org/pep-0008/#imports). These standards are " +"listed below:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:148 +msgid "Imports should be grouped in the following order:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:150 +msgid "Standard library imports." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:151 +msgid "Related third party imports." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:152 +msgid "Local application/library specific imports." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:154 +msgid "" +"While `flake8` will identify unused imports in your code, it won't fix or" +" identify issues with the order of package imports." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:157 +msgid "" +"`isort` will identify where imports in your code are out of order. It " +"will then modify your code, automatically reordering all imports. This " +"leaves you with one less thing to think about when cleaning up your code." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:162 +msgid "Example application of isort" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:164 +msgid "Code imports before `isort` is run:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:166 +msgid "" +"Below, the `pandas` is a third party package, `typing` is a core `Python`" +" package distributed with `Python`, and `examplePy.temperature` is a " +"first-party module which means it belongs to the same package as the file" +" doing the import. Also notice that there are no spaces in the imports " +"listed below." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:176 +msgid "From the project root, run:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:181 +msgid "Python file `temporal.py` imports after `isort` has been run" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:188 +msgid "Ruff" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:190 +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:196 +msgid "" +"`ruff` has some interesting features that distinguish it from other " +"linters:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:198 +msgid "Linter configuration in `pyproject.toml`" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:199 +msgid "Several hundred rules included, many of which are automatically fixable" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:200 +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:201 +msgid "" +"Fast execution time, makes a quick feedback loop possible even on large " +"projects." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:203 +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:211 +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:218 +msgid "How to use code formatter in your local workflow" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:220 +msgid "Linters, code formatters and your favorite coding tools" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:222 +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:228 +msgid "Use pre-commit hooks to run code formatters and linters on commits" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:230 +msgid "You can also setup a `pre-commit hook` in your Python package repository." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:232 +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:235 +msgid "Pre-commit hook example workflow" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:237 +msgid "The precommit workflow looks like this: You type and run:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:240 +msgid "`git commit -m \"message here\"` at the command line" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:242 +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:244 +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:248 +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:255 +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:259 +msgid "Diagram showing the steps of a pre-commit workflow from left to right." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:261 +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:274 +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:281 +msgid "General pre commit checks" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:283 +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:288 +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:291 +msgid "Pre-commit.ci" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:293 +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:296 +msgid "It will check every pull request using all of the pre-commit hook setting" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:297 +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:300 +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:302 +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:305 +msgid "Setting up a bot like this can be valuable because:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:307 +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:309 +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:311 +msgid "Setting up a git pre-commit hook" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:313 +msgid "To setup pre-commit locally, you need to do 3 things:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:315 +msgid "" +"Install pre-commit (and include it as a development requirement in your " +"repository)" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:325 +msgid "" +"Create a .pre-commit-config.yaml file in the root of your package " +"directory." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:327 +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:335 +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:338 +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:340 +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:343 +msgid "Summary" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:345 +msgid "" +"pyOpenSci suggests setting up a linter and a code styler for your " +"package, regardless of whether you use pre-commit hooks, CI or other " +"infrastructure to manage code format. Setting up these tools will give " +"you automatic feedback about your code's structure as you (or a " +"contributor) write it. And using a tool like black that format code for " +"you, reduce effort that you need to make surrounding decisions around " +"code format and style." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:1 +msgid "Complex Python package builds" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:3 +msgid "" +"This guide is focused on packages that are either pure-python or that " +"have a few simple extensions in another language such as C or C++." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:6 +msgid "" +"In the future, we want to provide resources for packaging workflows that " +"require more complex builds. If you have questions about these types of " +"package, please [add a question to our " +"discourse](https://pyopensci.discourse.group/) or open an [issue about " +"this guide specifically in the GitHub repo for this " +"guide](https://github.com/pyOpenSci/python-package-guide/issues). There " +"are many nuances to building and distributing Python packages that have " +"compiled extensions requiring non-Python dependencies at build time. For " +"an overview and thorough discussion of these nuances, please see [this " +"site.](https://pypackaging-native.github.io/)" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:8 +msgid "Pure Python Packages vs. packages with extensions in other languages" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:10 +msgid "" +"You can classify Python package complexity into three general categories." +" These categories can in turn help you select the correct package " +"frontend and backend tools." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:14 +msgid "" +"**Pure-python packages:** these are packages that only rely on Python to " +"function. Building a pure Python package is simpler. As such, you can " +"chose a tool below that has the features that you want and be done with " +"your decision!" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:16 +msgid "" +"**Python packages with non-Python extensions:** These packages have " +"additional components called extensions written in other languages (such " +"as C or C++). If you have a package with non-Python extensions, then you " +"need to select a build backend tool that allows additional build steps " +"needed to compile your extension code. Further, if you wish to use a " +"frontend tool to support your workflow, you will need to select a tool " +"that supports additional build setups. We suggest that you chose build " +"tool that supports custom build steps like Hatch." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:18 +msgid "" +"**Python packages that have extensions written in different languages " +"(e.g. Fortran and C++) or that have non Python dependencies that are " +"difficult to install (e.g. GDAL)** These packages often have complex " +"build steps (more complex than a package with just a few C extensions for" +" instance). As such, these packages require tools such as [scikit-" +"build](https://scikit-build.readthedocs.io/en/latest/) or [meson-" +"python](https://mesonbuild.com/Python-module.html) to build. NOTE: you " +"can use meson-python with PDM." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:21 +msgid "Mixing frontend and backend projects" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:23 +msgid "" +"It is sometimes necessary or desirable to use a build frontend with an " +"alternative build-backend. This is because some frontends do not have a " +"default backend (`build`), and this choice is placed on the maintainer. " +"Other backends (`hatch`) have a preferred backend (`hatchling`) but allow" +" the maintainer to migrate to another, while some backends (`poetry`) " +"only work with a single backend (`poetry-core`). Refer to (#python-" +"package-build-tools) for more information about frontend and backend " +"compatibility." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:29 +msgid "" +"In this packaging guide we recommend using `hatch` along with its " +"preferred backend `hatchling`. While this will be suitable for most " +"packages, an alternate backend may be used with Hatch if needed when " +"creating an extension module. A Python extension module is one that is " +"made up, either in part or entirely, of compiled code. In this case the " +"backend chosen (such as `meson-python`) must know how to compile the " +"extension language and bind it to Python. `hatchling` does not know how " +"to do this all on its own and must either make use of " +"[plugins](https://hatch.pypa.io/1.9/plugins/about/) or be replaced by a " +"backend that is already capable of building extension modules." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:37 +msgid "" +"In order to use a different backend you will need to edit your project's " +"`pyproject.toml`. If you have a `pyproject.toml` generated by the `hatch`" +" command, or from following the packaging tutorial, you may have to make " +"a change like this" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:8 +#: ../../package-structure-code/declare-dependencies.md:375 +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:25 +msgid "Todo" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:10 +msgid "" +"keep this comment - https://github.com/pyOpenSci/python-package-" +"guide/pull/106#issuecomment-1844278487 in this file for now - jeremiah " +"did a nice inventory of common shells and whether they need quotes or " +"not. it's really comprehensive. but do we want it in the guide?? it's " +"really useful for more advanced users i think." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:12 +msgid "" +"Following this comment: https://github.com/pyOpenSci/python-package-" +"guide/pull/106#pullrequestreview-1766663571" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:15 +msgid "Jonny will add a section that talks about:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:17 +msgid "" +"Why you specify dependencies How to specify dependencies When you use " +"different specifiers" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:22 +msgid "Python Package Dependencies" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:24 +msgid "What is a package dependency?" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:26 +msgid "" +"A Python package dependency refers to an external package or software " +"that your Python project:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:29 +msgid "needs to function properly." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:30 +msgid "" +"requires if someone wants to develop / work on improving your package " +"locally or" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:31 +msgid "" +"requires if a user wants to add additional functionality (that is not " +"core) to your package" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:33 +msgid "" +"A dependency is not part of your project's codebase. It is a package or " +"software that is called within the code of your project or during " +"development of your package." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:37 +msgid "Understanding optional vs. required dependencies" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:38 +msgid "" +"You can think about dependencies as being either optional or required. If" +" they are required, they will be listed in the `[dependency] =` table of " +"your `pyproject.toml` file. If they are optional, they will be listed in " +"the `[optional.dependencies]` table of your `pyproject.toml`." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:40 +msgid "You will learn about both below." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:46 +msgid "" +"There are two broad groups of Python package dependencies: those that are" +" optional and those that are required. Required packages are those that a" +" user needs to use your package. Optional dependencies are packages a " +"user can chose to install to add functionality to your package. Within " +"those 2 groups, there are three use cases that you can think about. 1. " +"Core dependencies are **required** for a user to use your package. 2. " +"Development dependencies are optional and only needed if someone wants to" +" work on your package locally. 3. Finally feature dependencies are " +"optional and add additional functionality to your package. Not all " +"packages will have feature dependencies." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:51 +msgid "Required (or core) dependencies" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:53 +msgid "" +"Required dependencies are called directly within your package's code. On " +"this page we refer to these dependencies as **core dependencies** as they" +" are needed in order to run your package. You should place your core or " +"required dependencies in the `[dependency]=` table of your " +"`pyproject.toml` file." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:56 +#: ../../package-structure-code/declare-dependencies.md:147 +msgid "Optional dependencies" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:58 +msgid "" +"Optional dependencies dependencies can be optionally installed by users " +"depending upon their needs. There are two broad groups of optional " +"dependencies:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:61 +msgid "" +"**Development dependencies**: These are dependencies that are required to" +" support development of your package. They include tools to run tests " +"such as `pytest`, linters (like `flake8` and `ruff`) and code formatters " +"such as `black` and even automation tools such as `nox` or `tox` that run" +" tasks." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:63 +msgid "" +"**Feature dependencies:** These are dependencies that a user can chose to" +" install to add functionality to your package." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:65 +msgid "" +"When a Python project is installed, the Python package manager (either " +"`pip` or `conda`) installs your package's dependencies automatically. " +"This ensures that when you call a function in a specific dependency, it " +"is available in your user's environment." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:70 +msgid "Dependencies can be added to your pyproject.toml file" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:72 +msgid "" +"In the [pyproject.toml overview page](pyproject-toml-python-package-" +"metadata), you learned how to set up a **pyproject.toml** file with basic" +" metadata for your package. On this page, you will learn how to specify " +"different types of dependencies in your `pyproject.toml`." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:79 +msgid "How do you declare dependencies?" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:81 +msgid "" +"We recommend that you declare your dependencies using your " +"`pyproject.toml` file. This ensures that all of the metadata associated " +"with your package is declared in a single place, making it simpler for " +"users and contributors to understand your package infrastructure." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:86 +msgid "" +"Previously, it was common to use a `requirements.txt` file to declare " +"package dependencies. However in recent years, the ecosystem has moved to" +" storing this information in your **pyproject.toml** file. You may notice" +" however that some projects still maintain a `requirements.txt` file for " +"specific local development needs." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:92 +msgid "Other ways you may see packages storing dependencies" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:95 +msgid "" +"If a project contains extensions written in other languages, you may need" +" a `setup.py` file. Or you may contribute to a package that us using " +"`setup.cfg` for dependency declaration. [Learn more about this in the " +"setuptools " +"documentation](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html" +"#declaring-required-dependency)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:100 +msgid "Add required dependencies to your pyproject.toml file" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:102 +msgid "" +"Your core project dependencies need to be installed by a package manager " +"such as `pip` or `conda` when a user installs your package. You can add " +"those dependencies to the `dependencies` array located within the " +"`[project]` table of your **pyproject.toml** file. This looks something " +"like this:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:121 +msgid "" +"Ideally, you should only list the packages that are necessary to install " +"and use your package in the `[dependencies]` section. This minimizes the " +"number of additional packages that your users must install as well as the" +" number of packages that depend upon your package must also install." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:128 +msgid "" +"Remember that fewer dependencies to install reduces the likelihood of " +"version mismatches in user environments." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:131 +msgid "A dependency example" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:133 +msgid "" +"Let's pretend you have a package called `plotMe` that creates beautiful " +"plots of data stored in `numpy` arrays. To create your plots in the " +"`plotMe` package, you use the `seaborn` package to stylize our plots and " +"also `numpy` to process array formatted data." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:135 +msgid "In the example above, the plotMe package, depends upon two packages:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:137 +msgid "seaborn" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:138 +msgid "numpy" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:140 +msgid "" +"This means that in order for plotMe to work in a user's `environment` " +"when installed, you also need to ensure that they have both of those " +"required `dependencies` installed in their environment too." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:142 +msgid "" +"Declaring a dependency in your `pyproject.toml` file will ensure that it " +"is listed as a required dependency when your package is published to PyPI" +" and that a package manager (`pip` or `conda`) will automatically install" +" it into a user's environment alongside your package:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:144 +msgid "`python -m pip install plotMe`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:149 +msgid "" +"Optional dependencies for building your documentation, running your tests" +" and building your package's distribution files are often referred to as " +"development dependencies. These are the dependencies that a user needs to" +" work on your package locally and perform tasks such as:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:151 +msgid "running your test suite" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:152 +msgid "building your documentation" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:153 +msgid "linting and other code cleanup tools" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:155 +msgid "" +"These dependencies are considered optional, because they are not required" +" to install and use your package. Feature dependencies are considered " +"optional and should also be placed in the `[optional.dependencies]` " +"table." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:158 +msgid "" +"Optional dependencies can be stored in an `[optional.dependencies]` table" +" in your **pyproject.toml** file." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:161 +msgid "" +"It's important to note that within the `[optional.dependencies]` table, " +"you can store additional, optional dependencies within named sub-groups. " +"This is a different table than the dependencies array located within the " +"`[project]` table discussed above which contains a single array with a " +"single list of required packages." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:163 +msgid "Create optional dependency groups" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:165 +msgid "To declare optional dependencies in your **pyproject.toml** file:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:167 +msgid "Add a `[optional.dependencies]` table to your **pyproject.toml** file." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:168 +msgid "Create named groups of dependencies using the syntax:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:170 +msgid "`group-name = [\"dep1\", \"dep2\"]`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:172 +msgid "Installing packages from GitHub / Gitlab" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:175 +msgid "" +"If you have dependencies that need to be installed directly from GitHub " +"using a `git+https` installation approach, you can do so using the " +"pyproject.toml file like so:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:185 +msgid "" +"IMPORTANT: For security reasons, if your library depends on a GitHub-" +"hosted project, you will need to point to a specific commit/tag/hash of " +"that repository in order to upload your project to PyPI" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:190 +msgid "" +"Below we've created three sets of optional development dependencies " +"named: tests, docs and lint. We've also added a set of feature " +"dependencies." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:213 +msgid "Additional dependency resources" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:215 +msgid "" +"[Learn more: View PyPA's overview of declaring optional " +"dependencies](https://packaging.python.org/en/latest/specifications" +"/declaring-project-metadata/#dependencies-optional-dependencies)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:217 +msgid "" +"[Dependency " +"specifiers](https://packaging.python.org/en/latest/specifications" +"/dependency-specifiers/)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:221 +msgid "Install dependency groups" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:226 +msgid "" +"Diagram showing a ven diagram with three sections representing the " +"dependency groups listed above - docs feature and tests. In the center it" +" says your-package and lists the core dependencies of that package " +"seaborn and numpy. To the right are two arrows. The first shows the " +"command python - m pip install your-package. it them shows how installing" +" your package that way installs only the package and the two core " +"dependencies into a users environment. Below is a second arrow with " +"python -m pip install youPackage[tests]. This leads to an environment " +"with both the package dependencies - your-package, seaborn and numpy and " +"also the tests dependencies including pytest and pytest-cov" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:228 +msgid "" +"When a user installs your package locally using python -m pip install " +"your-package only your package and it's core dependencies get installed. " +"When they install your package `[tests]` pip will install both your " +"package and its core dependencies plus any of the dependencies listed " +"within the tests array of your `[optional.dependencies]` table." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:231 +msgid "Using `python -m pip install` vs. `pip install`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:233 +msgid "" +"In all of the examples in this guide, you will notice we are calling " +"`pip` using the syntax:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:236 +msgid "`python -m pip`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:238 +msgid "" +"Calling pip using `python -m` ensures that the `pip` that you are using " +"to install your package comes from your current active Python " +"environment. We strongly suggest that you use this approach whenever you " +"call `pip` to avoid installation conflicts." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:242 +msgid "" +"To ensure this works as you want it to, activate your package's " +"development environment prior to installing anything using `pip`." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:246 +msgid "" +"You can install development dependencies using the groups that you " +"defined above using the syntax:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:249 +msgid "`python -m pip install \".[docs]\"`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:251 +msgid "Above you install:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:252 +msgid "dependencies needed for your documentation (`docs`)," +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:253 +msgid "required package dependencies in the `dependency` array and" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:254 +msgid "your package" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:256 +msgid "" +"using pip. Below you install your package, required dependencies and " +"optional test dependencies." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:259 +#: ../../package-structure-code/declare-dependencies.md:277 +msgid "`python -m pip install \".[tests]\"`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:261 +msgid "" +"You can install multiple dependency groups in the " +"`[optional.dependencies]` table using:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:263 +msgid "`python -m pip install \".[docs, tests, lint]\"`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:266 +msgid "For zsh shell users" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:270 +msgid "" +"There are different shell applications that you and your package " +"contributors might use." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:271 +msgid "zsh is the shell that comes by default on newer Mac OS computers" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:272 +msgid "Windows users may use a tool such as git bash" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:274 +msgid "" +"Some shells don't support unquoted brackets (`[tests]`) which is why we " +"add quotes to the command in this guide like this:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:279 +msgid "" +"In some cases you may see commands without the quotes in guidebooks or " +"contributing guides like the example below:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:282 +msgid "`python -m pip install your-package[tests]`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:284 +msgid "" +"Calling your-package[tests] without the double quotes will work on some " +"shells *but not all*." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:287 +msgid "Combining sets of dependencies" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:289 +msgid "" +"Above we reviewed how to install dependencies from your `pyproject.toml`." +" In some cases you may want to group sets of dependencies like so:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:302 +msgid "" +"The above allows you to install both the tests and docs dependency lists " +"using the command:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:305 +msgid "`python -m pip install \".[dev]\"`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:308 +msgid "When you install dependencies using the above syntax:" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:310 +msgid "`python -m pip install \".[tests, docs]\"`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:312 +msgid "`pip` will also install your package and its core dependencies." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:316 +msgid "Where does conda fit in?" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:319 +msgid "" +"The `pyproject.toml` file allows you to list any Python package published" +" on PyPI (or on GitHub/ GitLab) as a dependency. Once you create this " +"file, declare dependencies, [build your package](python-package-" +"distribution-files-sdist-wheel.md) and [publish your package to PyPI" +"](publish-python-package-pypi-conda.md), people can install both your " +"package and all of it's dependencies with one command." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:322 +msgid "`python -m pip install your-package`" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:324 +msgid "This works great if your package is pure-python (no other languages used)." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:326 +msgid "" +"Some packages, particularly in the scientific Python ecosystem, require " +"dependencies that are not written in Python. Conda was created to support" +" distribution of tools that have code written in both Python and " +"languages other than Python." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:329 +msgid "Support conda users with environment.yml files" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:331 +msgid "" +"The above workflow assumes that you want to publish your package on PyPI." +" And then you plan to publish to conda-forge (optionally), [by submitting" +" a recipe using grayskull](https://www.pyopensci.org/python-package-guide" +"/package-structure-code/publish-python-package-pypi-conda.html)." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:333 +msgid "" +"If you want to support conda users, you may want to also maintain a conda" +" environment that they can use to install your package. Maintaining a " +"conda environment will also help you test that your package installs as " +"you expect into a conda environment." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:336 +msgid "A note for conda users" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:339 +msgid "" +"If you use a conda environment for developing your tool, keep in mind " +"that when you install your package using `python -m pip install -e .` (or" +" using pip in general), dependencies will be installed from PyPI rather " +"than conda." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:341 +msgid "" +"Thus, if you are running a conda environment, installing your package in " +"\"editable\" mode risks dependency conflicts. This is particularly " +"important if you have a spatial package that requires geospatial system " +"libraries like GDAL or another system-level dependency." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:343 +msgid "" +"Alternatively, you can install your package using `python -m pip install " +"-e . --no-deps` to only install the package. And install the rest of your" +" dependencies using a conda environment file." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:346 +msgid "Dependencies in Read the Docs" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:348 +msgid "" +"Now that you have your dependencies specified in your project, you can " +"use them to support other workflows such as publishing to Read the Docs." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:350 +msgid "" +"[Read the Docs](https://readthedocs.org) is a documentation platform with" +" a continuous integration / continuous deployment service that " +"automatically builds and publishes your documentation." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:352 +msgid "" +"If you are using Read the Docs to build your documentation, then you may " +"need to install your dependencies using a **readthedocs.yaml** file." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:354 +msgid "" +"Below is an example of installing the **docs** section of your dependency" +" table in the pyproject.toml file within a readthedocs.yaml file." +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:366 +msgid "Read the Docs and Python packages" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:370 +msgid "" +"[Learn more about creating a `readthedocs.yaml` file here. " +"](https://docs.readthedocs.io/en/stable/config-file/index.html)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:371 +msgid "" +"If you want to install dependencies using Poetry in Read the Docs, [you " +"can learn more here.](https://docs.readthedocs.io/en/stable/build-" +"customization.html#install-dependencies-with-poetry)" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:376 +msgid "This is hidden. TO" +msgstr "" + +#: ../../package-structure-code/intro.md: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 "Build Your Package" +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 "Complex Builds" +msgstr "" + +#: ../../package-structure-code/intro.md:163 +msgid "Package structure & code style" +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 "Publishing a package" +msgstr "" + +#: ../../package-structure-code/intro.md:1 +msgid "Python package structure information" +msgstr "" + +#: ../../package-structure-code/intro.md:3 +msgid "" +"This section provides guidance on your Python package's structure, code " +"formats and style. It also reviews the various packaging tools that you " +"can use to support building and publishing your package." +msgstr "" + +#: ../../package-structure-code/intro.md:7 +msgid "" +"If you are confused by Python packaging, you are not alone! The good news" +" is there are some great modern packaging tools that ensure that you're " +"following best practices. Here, we review tool features and suggest tools" +" that might be best fitted for your workflow." +msgstr "" + +#: ../../package-structure-code/intro.md:19 +msgid "✨ 1. Package file structure ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:23 +msgid "" +"src layout, flat layout and where should tests folders live? No matter " +"what your level of packaging knowledge is, this page will help you decide" +" upon a package structure that follows modern python best practices." +msgstr "" + +#: ../../package-structure-code/intro.md:28 +msgid "✨ 2. Learn about building your package ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:32 +msgid "" +"To publish your Python package on PyPI, you will need to first build it. " +"The act of \"building\" refers to the process of placing your package " +"code and metadata into a format that can be published on PyPI. Learn more" +" about building your Python package." +msgstr "" + +#: ../../package-structure-code/intro.md:41 +msgid "✨ 4. Add metadata ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:45 +msgid "" +"Learn how to add project metadata to your Python package to support both " +"filtering on PyPI and also the metadata that a package installer needs to" +" build and install your package." +msgstr "" + +#: ../../package-structure-code/intro.md:52 +msgid "✨ 3. What Python package tool should you use? ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:56 +msgid "" +"Learn more about the suite of packaging tools out there. And learn which " +"tool might be best for you." +msgstr "" + +#: ../../package-structure-code/intro.md:62 +msgid "✨ 4. Publish to PyPI and Conda ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:66 +msgid "" +"If you have a pure Python package, it's a straight forward process to " +"publish to both PyPI and then a Conda channel such as conda-forge. Learn " +"more here." +msgstr "" + +#: ../../package-structure-code/intro.md:73 +msgid "✨ 5. Setup package versioning ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:77 +msgid "" +"Semver (numeric versioning) and Calver (versioning using the date) are 2 " +"common ways to version a package. Which one should you pick? Learn more " +"here." +msgstr "" + +#: ../../package-structure-code/intro.md:83 +msgid "✨ 6. Code style & linters ✨" +msgstr "" + +#: ../../package-structure-code/intro.md:87 +msgid "" +"Black, blue, flake8, Ruff - which tools can help you ensure your package " +"follows best practices for code format? Learn more about the options and " +"why this is important here." +msgstr "" + +#: ../../package-structure-code/intro.md:95 +msgid "" +"Figure showing a decision tree with the various packaging tool front-end " +"and back-end options." +msgstr "" + +#: ../../package-structure-code/intro.md:97 +msgid "" +"Diagram showing the various front-end build tools that you can select " +"from. See the packaging tools page to learn more about each tool." +msgstr "" + +#: ../../package-structure-code/intro.md:102 +msgid "" +"If you are considering submitting a package for peer review, have a look " +"at the bare-minimum [editor checks](https://www.pyopensci.org/software-" +"peer-review/how-to/editor-in-chief-guide.html#editor-checklist-template) " +"that pyOpenSci performs before a review begins. These checks are useful " +"to explore for both authors planning to submit a package to us for review" +" and for anyone who is just getting started with creating a Python " +"package." +msgstr "" + +#: ../../package-structure-code/intro.md:109 +msgid "What you will learn here" +msgstr "" + +#: ../../package-structure-code/intro.md:111 +msgid "In this section of our Python packaging guide, we:" +msgstr "" + +#: ../../package-structure-code/intro.md:113 +msgid "" +"Provide an overview of the options available to you when packaging your " +"tool." +msgstr "" + +#: ../../package-structure-code/intro.md:115 +msgid "" +"Suggest tools and approaches that both meet your needs and also support " +"existing standards." +msgstr "" + +#: ../../package-structure-code/intro.md:117 +msgid "" +"Suggest tools and approaches that will allow you to expand upon a " +"workflow that may begin as a pure Python tool and evolve into a tool that" +" requires addition layers of complexity in the packaging build." +msgstr "" + +#: ../../package-structure-code/intro.md:120 +msgid "" +"Align our suggestions with the most current, accepted [PEPs (Python " +"Enhancement Protocols)](https://peps.python.org/pep-0000/) and the " +"[Scientific Python community SPECs](https://scientific-" +"python.org/specs/)." +msgstr "" + +#: ../../package-structure-code/intro.md:123 +msgid "" +"In an effort to maintain consistency within our community, we also align " +"with existing best practices being implemented by developers of core " +"Scientific Python packages such as Numpy, SciPy and others." +msgstr "" + +#: ../../package-structure-code/intro.md:127 +msgid "Guidelines for pyOpenSci's packaging recommendations" +msgstr "" + +#: ../../package-structure-code/intro.md:129 +msgid "" +"The flexibility of the Python programming language lends itself to a " +"diverse range of tool options for creating a Python package. Python is so" +" flexible that it is one of the few languages that can be used to wrap " +"around other languages. The ability of Python to wrap other languages is " +"one the reasons you will often hear Python described as a [\"glue\" " +"language](https://numpy.org/doc/stable/user/c-info.python-as-glue.html)\"" +msgstr "" + +#: ../../package-structure-code/intro.md:135 +msgid "" +"If you are building a pure Python package, then your packaging setup can " +"be simple. However, some scientific packages have complex requirements as" +" they may need to support extensions or tools written in other languages " +"such as C or C++." +msgstr "" + +#: ../../package-structure-code/intro.md:139 +msgid "" +"To support the many different uses of Python, there are many ways to " +"create a Python package. In this guide, we suggest packaging approaches " +"and tools based on:" +msgstr "" + +#: ../../package-structure-code/intro.md:142 +msgid "" +"What we think will be best and easiest to adopt for those who are newer " +"to packaging." +msgstr "" + +#: ../../package-structure-code/intro.md:144 +msgid "Tools that we think are well maintained and documented." +msgstr "" + +#: ../../package-structure-code/intro.md:145 +msgid "" +"A shared goal of standardizing packaging approaches across this " +"(scientific) Python ecosystem." +msgstr "" + +#: ../../package-structure-code/intro.md:148 +msgid "" +"Here, we also try to align our suggestions with the most current, " +"accepted [Python community](https://packaging.python.org/en/latest/) and " +"[scientific community](https://scientific-python.org/specs/)." +msgstr "" + +#: ../../package-structure-code/intro.md:151 +msgid "Suggestions in this guide are not pyOpenSci review requirements" +msgstr "" + +#: ../../package-structure-code/intro.md:154 +msgid "" +"The suggestions for package layout in this section are made with the " +"intent of being helpful; they are not specific requirements for your " +"package to be reviewed and accepted into our pyOpenSci open source " +"ecosystem." +msgstr "" + +#: ../../package-structure-code/intro.md:158 +msgid "" +"Please check out our [package scope page](https://www.pyopensci.org" +"/software-peer-review/about/package-scope.html) and [review requirements " +"in our author guide](https://www.pyopensci.org/software-peer-review/how-" +"to/author-guide.html#) if you are looking for pyOpenSci's Python package " +"review requirements!" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:1 +msgid "Publishing Your Package In A Community Repository: PyPI or Anaconda.org" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:5 +msgid "" +"pyOpenSci requires that your package has an distribution that can be " +"installed from a public community repository such as PyPI or a conda " +"channel such as `bioconda` or `conda-forge` on Anaconda.org." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:9 +msgid "" +"Below you will learn more about the various publishing options for your " +"Python package." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:14 +msgid "" +"Installing packages in the same environment using both pip and conda can " +"lead to package conflicts." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:16 +msgid "" +"To minimize conflicts for users who may be using conda (or pip) to manage" +" local environments, consider publishing your package to both PyPI and " +"the conda-forge channel on Anaconda.org." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:18 +msgid "" +"Below you will learn more specifics about the differences between PyPI " +"and conda publishing of your Python package." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:24 +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:6 +msgid "" +"Image showing the progression of creating a Python package, building it " +"and then publishing to PyPI and conda-forge. You take your code and turn " +"it into distribution files (sdist and wheel) that PyPI accepts. then " +"there is an arrow towards the PyPI repository where ou publish both " +"distributions. From PyPI if you create a conda-forge recipe you can then " +"publish to conda-forge." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:26 +msgid "" +"Once you have published both package distributions (the source " +"distribution and the wheel) to PyPI, you can then publish to conda-forge." +" conda-forge requires a source distribution on PyPI in order to build " +"your package on conda-forge. You do not need to rebuild your package to " +"publish to conda-forge." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:29 +msgid "What is PyPI" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:31 +msgid "" +"[PyPI](https://pypi.org/) is an online Python package repository that you" +" can use to both find and install and publish your Python package. There " +"is also a test PyPI repository where you can test publishing your package" +" prior to the final publication on PyPI." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:36 +msgid "" +"Many if not most Python packages can be found on PyPI and are thus " +"installable using `pip`." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:38 +msgid "" +"The biggest different between using pip and conda to install a package is" +" that conda can install any package regardless of the language(s) that it" +" is written in. Whereas `pip` can only install Python packages." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:43 +msgid "Click here for a tutorial on publishing your package to PyPI." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:52 +msgid "" +"On the package build page, we discussed the [two package distribution " +"types that you will create when making a Python package](python-package-" +"distribution-files-sdist-wheel): SDist (packaged as a .tar.gz or .zip) " +"and Wheel (.whl) which is really a zip file. Both of those file " +"\"bundles\" will be published on PyPI when you use [a standard build tool" +"](python-package-build-tools) to build your package." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:60 +msgid "What is conda and Anaconda.org?" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:62 +msgid "" +"conda is an open source package and environment management tool. conda " +"can be used to install tools from the [Anaconda " +"repository](https://repo.anaconda.com/)." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:66 +msgid "" +"Anaconda.org contains public and private repositories for packages. These" +" repositories are known as channels (discussed below)." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:69 +msgid "A brief history of conda's evolution" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:72 +msgid "" +"The conda ecosystem evolved years ago to provide support for, and " +"simplify the process of, managing software dependencies in scientific " +"Python projects." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:76 +msgid "" +"Many of the core scientific Python projects depend upon or wrap around " +"tools and extensions that are written in other languages, such as C++. In" +" the early stages of the scientific ecosystem's development, these non-" +"Python extensions and tools were not well supported on PyPI, making " +"publication difficult. In recent years there is more support for complex " +"builds that allow developers to bundle non-Python code into a Python " +"distribution using the [wheel distribution format](python-wheel)." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:78 +msgid "" +"Conda provides a mechanism to manage these dependencies and ensure that " +"the required packages are installed correctly." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:82 +msgid "" +"While conda was originally created to support Python packages, it is now " +"used across all languages. This cross-language support makes it easier " +"for some packages to include and have access to tools written in other " +"languages, such as C/C++ (gdal), Julia, or R. Creating an environment " +"that mixes all of these packages is usually easier and more consistent " +"with full-fledged package managers like conda." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:90 +msgid "conda channels" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:92 +msgid "" +"conda built packages are housed within repositories that are called " +"channels. The conda package manager can install packages from different " +"channels." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:95 +msgid "" +"There are several core public channels that most people use to install " +"packages using conda, including:" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:98 +msgid "" +"**defaults:** this is a channel managed by Anaconda. It is the version of" +" the Python packages that you will install if you install the Anaconda " +"Distribution. Anaconda (the company) decides what packages live on the " +"`defaults` channel." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:99 +msgid "" +"[**conda-forge:**](https://anaconda.org/conda-forge) this is a community-" +"driven channel that focuses on scientific packages. This channel is ideal" +" for tools that support geospatial data. Anyone can publish a package to " +"this channel." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:100 +msgid "" +"[**bioconda**](https://anaconda.org/bioconda): this channel focuses on " +"biomedical tools." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:102 +msgid "" +"**conda-forge** emerged as many of the scientific packages did not exist " +"in the `defaults` Anaconda channel." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:107 +msgid "" +"Graphic with the title Python package repositories. Below it says " +"Anything hosted on PyPI can be installed using pip install. Packaging " +"hosted on a conda channel can be installed using conda install. Below " +"that there are two rows. the top row says conda channels. next to it are " +"three boxes one with conda-forge, community maintained; bioconda and then" +" default - managed by the anaconda team. Below that there is a row that " +"says PyPI servers. PyPI - anyone can publish to PyPI. and test PyPI. a " +"testbed server for you to practice." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:109 +msgid "" +"Conda channels represent various repositories that you can install " +"packages from. Because conda-forge is community maintained, anyone can " +"submit a recipe there. PyPI is also a community maintained repository. " +"Anyone can submit a package to PyPI and test PyPI. Unlike conda-forge " +"there are no manual checks of packages submitted to PyPI." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:113 +msgid "conda channels, PyPI, conda, pip - Where to publish your package" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:115 +msgid "" +"You might be wondering why there are different package repositories that " +"can be used to install Python packages." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:118 +msgid "" +"And more importantly you are likely wondering how to pick the right " +"repository to publish your Python package." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:121 +msgid "The answer to both questions relates dependency conflicts." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:125 +msgid "" +"Image showing an XKCD comic that shows a web of Python environments and " +"tools and installations. At the bottom is says - My python environment " +"has become so degraded that my laptop has been declared a superfund site." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:127 +msgid "" +"Installing Python and Python packages from different repositories can " +"lead to environment conflicts where a version of on package doesn't work " +"with a version of another package. To keep your environments clean and " +"working, it's best to install packages from the same repository. So use " +"pip to install everything. Or use conda. If you can, try to avoid " +"installing package from both pip and conda into the same environment." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:135 +msgid "Managing Python package dependency conflicts" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:137 +msgid "" +"Python environments can encounter conflicts because Python tools can be " +"installed from different repositories. Broadly speaking, Python " +"environments have a smaller chance of dependency conflicts when the tools" +" are installed from the same package repository. Thus environments that " +"contain packages installed from both pip and conda are more likely to " +"yield dependency conflicts." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:144 +msgid "" +"Similarly installing packages from the default anaconda package mixed " +"with the conda-forge channel can also lead to dependency conflicts." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:146 +msgid "" +"Many install packages directly from conda `defaults` channel. However, " +"because this channel is managed by Anaconda, the packages available on it" +" are limited to those that Anaconda decides should be core to a stable " +"installation. The conda-forge channel was created to complement the " +"`defaults` channel. It allows anyone to submit a package to be published " +"in the channel . Thus, `conda-forge` channel ensures that a broad suite " +"of user-developed community packages can be installed from conda." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:150 +msgid "" +"Take-aways: If you can, publish on both PyPI and conda-forge to " +"accommodate more users of your package" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:152 +msgid "" +"The take-away here for maintainers is that if you anticipate users " +"wanting to use conda to manage their local environments (which many do), " +"you should consider publishing to both PyPI and the conda-forge channel " +"(_more on that below_)." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:157 +msgid "Additional resources" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:158 +msgid "" +"[learn more about why conda-forge was created, here](https://conda-" +"forge.org/docs/user/introduction.html)" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:160 +msgid "" +"[To learn more about conda terminology, check out their " +"glossary.](https://docs.conda.io/projects/conda/en/latest/glossary.html )" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:165 +msgid "How to submit to conda-forge" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:167 +msgid "" +"While pyOpenSci doesn't require you to add your package to conda-forge, " +"we encourage you to consider doing so!" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:170 +msgid "" +"Once your package is on PyPI, the process to add your package to conda-" +"forge is straight forward to do. [You can follow the detailed steps " +"provided by the conda-forge maintainer team.](https://conda-" +"forge.org/docs/maintainer/adding_pkgs.html)." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:175 +msgid "Click here for a tutorial on adding your package to conda-forge." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:182 +msgid "If you want a step by step tutorial, click here." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:185 +msgid "" +"Once your package is added, you will have a feedstock repository on " +"GitHub with your packages name" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:188 +msgid "" +"[Here is an example conda-forge feedstock for the pyOpenSci approved " +"package - movingpandas](https://github.com/conda-forge/movingpandas-" +"feedstock)" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:191 +msgid "Maintaining your conda-forge package repository" +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:193 +msgid "" +"Once your package is on the conda-forge channel, maintaining it is " +"simple. Every time that you push a new version of your package to PyPI, " +"it will kick off a continuous integration build that updates your package" +" in the conda-forge repository. Once that build is complete, you will get" +" a notification to review the update." +msgstr "" + +#: ../../package-structure-code/publish-python-package-pypi-conda.md:199 +msgid "" +"You can merge the pull request for that update once you are happy with " +"it. A ready-to-merge PR usually means ensuring that your project's " +"dependencies (known as runtime requirements) listed in the updated YAML " +"file found in the pull request match the PyPI metadata of the new " +"release." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:1 +msgid "Use a pyproject.toml file for your package configuration & metadata" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:12 +msgid "Important pyproject.toml take aways" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:16 +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:17 +msgid "" +"There are only two _required_ fields in the **[project]** table: " +"**name=** and **version=**." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:18 +msgid "" +"We suggest you add additional metadata to your `pyproject.toml` file as " +"it will make it easier for users to find your project on PyPI." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:19 +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:20 +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:21 +msgid "" +"**python-requires**: is important to have in your `pyproject.toml` file " +"as it helps pip install your package." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:27 +msgid "when these are published, remove this todo" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:36 +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:50 +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:60 +msgid "About the pyproject.toml file" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:62 +msgid "" +"Every modern Python package should include a `pyproject.toml` file. If " +"your project is pure Python and you're using a `setup.py` or `setup.cfg` " +"file to describe its metadata, you should consider migrating your " +"metadata and build information to a `pyproject.toml` file." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:64 +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:66 +msgid "What happened to setup.py & how do i migrate to pyproject.toml?" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:68 +msgid "" +"Prior to August 2017, Python package metadata was stored either in the " +"`setup.py` file or a `setup.cfg` file. In recent years, there has been a " +"shift to storing Python package metadata in a much more user-readable " +"`pyproject.toml` format. Having all metadata in a single file:" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:70 +msgid "simplifies package management," +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:71 +msgid "" +"allows you to use a suite of different [build " +"backends](https://www.pyopensci.org/python-package-guide/package-" +"structure-code/python-package-build-tools.html#build-back-ends) such as " +"(flit-core, hatchling, pdm-build), and" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:72 +msgid "aligns with modern best practices." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:79 +msgid "" +"The standard file that Python packages use to [specify build requirements" +" and metadata is called a " +"**pyproject.toml**](https://packaging.python.org/en/latest/specifications" +"/declaring-project-metadata/). Adding metadata, build requirements and " +"package dependencies to a **pyproject.toml** file replaces storing that " +"information in a setup.py or setup.cfg file." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:84 +msgid "About the .toml format" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:86 +msgid "" +"The **pyproject.toml** file is written in [TOML (Tom's Obvious, Minimal " +"Language) format](https://toml.io/en/). TOML is an easy-to-read structure" +" that is founded on key/value pairs. Each section in the " +"**pyproject.toml** file contains a `[table identifier]`. Below that table" +" identifier are key/value pairs that support configuration for that " +"particular table." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:90 +msgid "Below `[build-system]` is considered a table in the toml language." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:91 +msgid "Within the `build-system` table below `requires =` is a key." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:92 +msgid "" +"The associated value for `requires` is an array containing the value " +"`\"hatchling\"`." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:100 +msgid "How the pyproject.toml is used when you build a package" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:104 +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:81 +msgid "" +"When you publish to PyPI, you will notice that each package has metadata " +"listed. Let’s have a look at [xclim](https://pypi.org/project/xclim/), " +"one of our [pyOpenSci packages](https://www.pyopensci.org/python-" +"packages.html). Notice that on the PyPI landing page you see some " +"metadata about the package including python, maintainer information and " +"more. PyPI is able to populate this metadata because it was defined using" +" correct syntax and classifiers by Xclim's maintainers, [pyproject.toml " +"file](https://github.com/Ouranosinc/xclim/blob/master/pyproject.toml). " +"This metadata when the xclim package is built, is translated into a " +"distribution file that allows PyPI to read the metadata and print it out " +"on their website." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:106 +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:83 +msgid "" +"Image showing the left side bar of PyPI for the package xclim. The " +"section at the top says Classifier. Below there is a list of items " +"including Development status, intended audience, License, natural " +"language, operating system, programming language and topic. Below each of" +" those sections are various classifier options.\" width=\"300px\">" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:111 +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:88 +msgid "" +"When you add the classifier section to your pyproject.toml and your " +"package is built, the build tool organizes the metadata into a format " +"that PyPI can understand and represent on your PyPI landing page. These " +"classifiers also allow users to sort through packages by version of " +"python they support, categories and more." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:116 +msgid "Benefits of using a pyproject.toml file" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:118 +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:126 +msgid "Setup.py is still useful for complex package builds" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:130 +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:136 +msgid "Optional vs. Required pyproject.toml file fields" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:138 +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:140 +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:142 +msgid "Required fields for the [project] table" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:144 +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:146 +msgid "Name: This is the name of your project provided as a string" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:147 +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:149 +msgid "Optional fields to include in the `[project]` table" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:151 +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:156 +msgid "**Description:** this is a short one-line description of your package." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:157 +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:158 +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:159 +msgid "**License:** the license you are using" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:160 +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:161 +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:169 +msgid "" +"**dependencies:** dependencies are optional but we strongly suggest you " +"include them in your pyproject.toml. Dependencies will be installed by " +"pip when your project is installed creating a better user-experience." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:171 +msgid "" +"**`[project.optional-dependencies]`:** the optional or development " +"dependencies will be installed if someone runs `python -m pip install " +"projectname[dev]`. This is a nice way to include your development " +"dependencies for users who may wish to contribute to your project." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:173 +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:174 +msgid "" +"**classifiers:** The classifiers section of your metadata is also " +"important for the landing page of your package in PyPI and for filtering " +"of packages in PyPI. A list of [all options for classifiers can be found " +"her](https://PyPI.org/classifiers/)e. Some of the classifiers that you " +"should consider including" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:175 +msgid "Development Status" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:176 +msgid "Intended Audience" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:177 +msgid "Topic" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:178 +msgid "LIcense" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:179 +msgid "Programming language" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:181 +msgid "Advanced options in the pyproject.toml file" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:183 +msgid "The examples at the bottom of this page contain ..." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:185 +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:186 +msgid "" +"Here is an example of[ a package that has entry point " +"script](https://github.com/pyOpenSci/update-web-" +"metadata/blob/main/pyproject.toml#L60)s. Notice that there are several " +"core scripts defined in that package that perform sets of tasks. " +"pyOpenSci is using those scripts to process their metadata." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:187 +msgid "" +"**Dynamic Fields:** if you have fields that are dynamically populated. " +"One example of this is if you are using scm / version control based " +"version with tools like `setuptooms_scm`, then you might use the dynamic " +"field. such as version (using scm) **dynamic = [\"version\"]**" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:189 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Add dependencies to your pyproject.toml file" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:191 +msgid "" +"The pyproject.toml file can also be used as a replacement for the " +"requirements.txt file which has been traditionally used to store " +"development dependencies such as pytest, code formatters such as Black " +"and documentation tools such as sphinx." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:193 +msgid "" +"To add dependencies to your build, add a `[project.optional-" +"dependencies]` table to your pyproject.toml file." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:195 +msgid "Then specify dependency groups as follows:" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:202 +msgid "Following the above example, you install dependencies like this:" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:204 +msgid "`python -m pip install -e .[tests]`" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:206 +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:208 +msgid "To install all dependencies and also your package, you'd use:" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:210 +msgid "`python -m pip install -e .[tests,lint,docs]`" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:212 +msgid "Recursive dependencies" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:216 +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:219 +msgid "Example pyproject.toml for building using hatchling" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:221 +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:229 +msgid "Notice that dependencies are specified in this file." +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:231 +msgid "Example pyproject.toml for building using setuptools" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:233 +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:237 +msgid "In this example package setup you use:" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:239 +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:240 +msgid "" +"**setuptools_scm** to manage package version updates using version " +"control tags" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:242 +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:245 +msgid "`requires =`" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:246 +msgid "`build-back-end =`" +msgstr "" + +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md:253 +msgid "" +"[Click here to read about our packaging build tools including PDM, " +"setuptools, Poetry and Hatch.](/package-structure-code/python-package-" +"build-tools)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:1 +msgid "Python Packaging Tools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:3 +msgid "Tools for building your package" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:5 +msgid "" +"There are a several different build tools that you can use to [create " +"your Python package's _sdist_ and _wheel_ distributions](python-package-" +"distribution-files-sdist-wheel). Below, we discuss the features, benefits" +" and limitations of the most commonly used Python packaging tools. We " +"focus on pure-python packages in this guide. However, we also highlight " +"tools that currently support packages with C/C++ and other language " +"extensions." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:13 +msgid "" +"Decision tree diagram showing the various front and back end packaging " +"tools. You can decide what packaging tool to use by thinking about what " +"features you need. PDM and Hatch are currently the most flexible tools " +"as they also using different build back-ends. As such currently PDM and " +"Hatch are the tools we think beginners might appreciate most with Poetry " +"being a close second. Poetry is nice for pure Python projects." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:15 +msgid "" +"Diagram showing the different front end build tools available to use in " +"the Python package ecosystem that you can select from. We selected tools " +"to include in this diagram based upon the PyPI survey which helped us " +"understand the most populate tools in the ecosystem. Each tool has " +"different features as highlighted below." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:18 +msgid "" +"If you want to know more about Python packages that have extensions " +"written in other languages, [check out the page on complex package builds" +".](complex-python-package-builds)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:21 +msgid "Tools that we review here" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:23 +msgid "" +"In this section we have selected tools that were returned as the most " +"popular packaging tools in the PyPA survey. You will learn more about the" +" following tools on this page:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:27 +msgid "" +"[Twine](https://twine.readthedocs.io/en/stable/), [Build](https://pypa-" +"build.readthedocs.io/en/stable/) + " +"[setuptools](https://setuptools.pypa.io/en/latest/)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:28 +msgid "[Flit](https://flit.pypa.io/en/stable/)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:29 +msgid "[Hatch](https://hatch.pypa.io/latest/)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:30 +msgid "[PDM](https://pdm.fming.dev/latest/)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:31 +msgid "[Poetry](https://python-poetry.org/docs/)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:33 +msgid "Summary of tools Hatch vs. PDM vs. Poetry (and setuptools)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:35 +msgid "If you are looking for a quick summary, read below." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:37 +msgid "" +"In general, any modern tool that you select from this page will be great " +"to build your package. Selecting a tool comes down to the features that " +"you are looking for in your workflow." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:38 +msgid "" +"We suggest that beginners start with a modern workflow tool like PDM as " +"opposed to navigating the complexities of setuptools." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:39 +msgid "" +"If you are going to use Poetry (it is the most popular tool and does have" +" the best documentation) beware of the upper bounds dependency additions " +"and consider overriding dependencies when you add them. If you do that " +"Poetry will work well for pure-python builds! Poetry also has an active " +"discord where you can ask questions." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:41 +msgid "Below are some features that Hatch and PDM offer that Poetry does not." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:43 +msgid "PDM:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:45 +msgid "" +"Supports other back-ends making it ideal for builds that are not pure " +"Python. This means PDM is a great option for both pure python and more " +"complex Python builds as it supports meson-python and other build " +"backends." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:46 +msgid "Offers flexibility in dependency management which we like" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:47 +msgid "Offers lock files if you need them" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:49 +msgid "Hatch:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:51 +msgid "" +"Offers matrix environment management that allows you to run tests across " +"Python versions. If this feature is important to you, then Hatch is a " +"clear winner." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:52 +msgid "" +"Offers a Nox / Make file like tool to streamline your build workflow. If " +"you are looking to reduce the number of tools in your workflow, Hatch " +"might be for you." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:55 +msgid "Build front-end vs. build back-end tools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:57 +msgid "" +"To better understand your options, when it comes to building a Python " +"package, it's important to first understand the difference between a " +"build tool front-end and build back-end." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:62 +msgid "Build back-ends" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:64 +msgid "" +"Most packaging tools have a back-end build tool that builds you package " +"and creates associated [(sdist and wheel) distribution files](python-" +"package-distribution-files-sdist-wheel). Some tools, such as **Flit**, " +"only support pure-Python package builds. A pure-Python build refers to a " +"package build that does not have extensions that are written in another " +"programming language (such as `C` or `C++`)." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:71 +msgid "" +"Other packages that have C and C++ extensions (or that wrap other " +"languages such as fortran) require additional code compilation steps when" +" built. Back-ends such as **setuptools.build**, **meson.build** and " +"**scikit-build** support complex builds with custom steps. If your build " +"is particularly complex (i.e. you have more than a few `C`/`C++` " +"extensions), then we suggest you use **meson.build** or **scikit-build**." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:77 +msgid "Python package build front-ends" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:79 +msgid "" +"A packaging front-end tool refers to a tool that makes it easier for you " +"to perform common packaging tasks using similar commands. These tasks " +"include:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:82 +msgid "" +"[Build your packages (create the sdist and wheel distributions)](python-" +"package-distribution-files-sdist-wheel)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:83 +msgid "" +"Installing your package in a development mode (so it updates when you " +"update your code)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:84 +msgid "Publishing to PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:85 +msgid "Running tests" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:86 +msgid "Building documentation" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:87 +msgid "" +"Managing an environment or multiple environments in which you need to run" +" tests and develop your package" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:89 +msgid "" +"There are several Python packaging tools that you can use for pure Python" +" builds. Each front-end tool discussed below supports a slightly " +"different set of Python packaging tasks." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:93 +msgid "" +"For instance, you can use the packaging tools **Flit**, **Hatch** or " +"**PDM** to both build and publish your package to PyPI. However while " +"**Hatch** and **PDM** support versioning and environment management, " +"**Flit** does not. If you want a tool that supports dependency locking, " +"you can use **PDM** or **Poetry** but not **Hatch**. If you only need to " +"build your package's sdist and wheel distribution files, then you can " +"stick with PyPA's Build. You'd then use Twine to publish to PyPI." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:100 +msgid "" +"If you are using **Setuptools**, there is no default user-friendly build " +"front-end that performs multiple tasks. You will need to use **build** to" +" build your package and **twine** to publish to PyPI." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:103 +msgid "Example build steps that can be simplified using a front-end tool" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:105 +msgid "" +"Below, you can see how a build tool streamlines your packaging " +"experience. Example to build your package with **Hatch**:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:115 +msgid "Example build steps using the **setuptools** back-end and **build**:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:125 +msgid "Choosing a build back-end" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:127 +msgid "" +"Most front-end packaging tools have their own back-end build tool. The " +"build tool creates your package's (sdist and wheel) distribution files. " +"For pure Python packages, the main difference between the different build" +" back-ends discussed below is:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:132 +msgid "" +"How configurable they are - for example, do they allow you to add build " +"steps that support non python extensions?" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:133 +msgid "" +"How much you need to configure them to ensure the correct files are " +"included in your sdist and wheel distributions." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:135 +msgid "Build back-end support for non pure-python packages" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:137 +msgid "" +"It is important to note that some build back-ends, such as **Flit-core**," +" only support pure Python builds. Other back-ends support C and C++ " +"extensions as follows:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:140 +msgid "setuptools supports builds using C / C++ extensions" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:141 +msgid "" +"Hatchling (hatch's back-end) supports C / C++ extensions via plugins that" +" the developer creates to customize a build" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:142 +msgid "PDM's back-end supports C / C++ extensions by using setuptools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:143 +msgid "" +"Poetry's back-end supports C/C++ extensions however this functionality is" +" currently undocumented. As such we don't recommend using Poetry for " +"complex or non pure Python builds until it is documented." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:145 +msgid "" +"While we won't discuss more complex builds below, we will identify which " +"tools have documented support for C / C++ extensions." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:148 +msgid "An ecosystem of Python build tools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:150 +msgid "" +"Below we introduce several of the most commonly used Python packaging " +"build front-end tools. We highlight the features that each tool offers as" +" a way to help you decide what tool might be best for your workflow." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:154 +msgid "We do not suggest using setuptools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:157 +msgid "" +"We suggest that you pick one of the modern tools listed above rather than" +" setuptools because setuptools will require some additional knowledge to " +"set up correctly." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:161 +msgid "" +"We review setuptools as a back-end because it is still popular. However " +"it is not the most user friendly option." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:165 +msgid "" +"The most commonly used tools in the ecosystem are setuptools back-end " +"(with build) and Poetry (a front end tool with numerous features and " +"excellent documentation)." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:171 +msgid "" +"Graph showing the results of the 2022 PyPA survey of Python packaging " +"tools. On the x axis is percent response and on the y axis are the tools." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:173 +msgid "" +"The Python developers survey results (n=>8,000 PyPI users) show " +"setuptools and poetry as the most commonly used Python packaging tools. " +"The core tools that we've seen being used in the scientific community are" +" included here. [You can view the full survey results by clicking " +"here.](https://drive.google.com/file/d/1U5d5SiXLVkzDpS0i1dJIA4Hu5Qg704T9/view)" +" NOTE: this data represent maintainers across domains and is likely " +"heavily represented by those in web development. So this represents a " +"snapshot across the broader Python ecosystem." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:176 +msgid "Chose a build workflow tool" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:178 +msgid "The tools that we review below include:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:180 +msgid "Twine, Build + setuptools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:181 +#: ../../package-structure-code/python-package-build-tools.md:291 +msgid "Flit" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:182 +#: ../../package-structure-code/python-package-build-tools.md:331 +msgid "Hatch" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:183 +#: ../../package-structure-code/python-package-build-tools.md:215 +#: ../../package-structure-code/python-package-build-tools.md:230 +msgid "PDM" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:184 +#: ../../package-structure-code/python-package-build-tools.md:374 +msgid "Poetry" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:186 +msgid "" +"When you are selecting a tool, you might consider this general workflow " +"of questions:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:189 +msgid "" +"**Is your tool pure python? Yes?** You can use any tool that you wish! " +"Pick the tool that has the features that you want to use in your build " +"workflow. We suggest:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:191 +msgid "Flit, Hatch, PDM or Poetry (read below for more)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:193 +msgid "" +"**Does your tool have a few C or C++ extensions?** Great, we suggest " +"using **PDM** for the time being. It is the only tool in the list below " +"that has both documented workflow to support such extensions and support " +"for other back-ends in the case that build hooks are not enough for your " +"workflow. PDM supports other back-ends such as scikit-build and meson-" +"python that will allow you to fully customize your package's build." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:197 +msgid "" +"NOTE: You can also use Hatch for non pure python builds. Hatch, similar " +"to PDM, allows you to write your own build hooks or plugins to support " +"custom build steps. But currently, hatch does not support other build " +"back ends. Many of the core scientific packages are moving to meson-" +"python to build their packages. Thus, we appreciate that PDM can work " +"with meson-python specifically." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:199 +msgid "Python packaging tools summary" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:201 +msgid "" +"Below, we summarize features offered by the most popular build front end " +"tools. It is important to keep in mind that these front-end tools remove " +"the need to use other core tools in your workflow. For example if you use" +" setuptools, you will need to also use Build and Twine to build your " +"package and publish to PyPI. But if you use Poetry, Hatch or PDM you can " +"do all of those things using the same tool (e.g. `hatch build`, `hatch " +"publish` or `pdm build`, `pdm publish`)." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:204 +msgid "" +"Note that because setuptools does not offer a front-end interface, it is " +"not included in the table." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:208 +msgid "Package tool features table" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +msgid "Feature, Flit, Hatch, PDM, Poetry" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +msgid "Default Build Back-end" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +msgid "Flit-core" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +msgid "hatchling" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +msgid "Poetry-core" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +#: ../../package-structure-code/python-package-build-tools.md:251 +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Use Other Build Backends" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "✖" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +#: ../../package-structure-code/python-package-build-tools.md:251 +#: ../../package-structure-code/python-package-build-tools.md:304 +#: ../../package-structure-code/python-package-build-tools.md:348 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "✅" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Dependency management" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "Publish to PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +msgid "Version Control based versioning (using `git tags`)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +#: ../../package-structure-code/python-package-build-tools.md:251 +#: ../../package-structure-code/python-package-build-tools.md:348 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Version bumping" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Environment Management" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:215 +msgid "More than one maintainer? (bus factor)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:225 +msgid "Notes:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:227 +msgid "_Hatch plans to support dependency management in the future_" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:228 +msgid "" +"Poetry supports semantic versioning. Thus, it will support version " +"bumping following commit messages if you use a tool such as Python " +"Semantic Release" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:232 +msgid "" +"[PDM is a Python packaging and dependency management " +"tool](https://pdm.fming.dev/latest/). PDM supports builds for pure Python" +" projects. It also provides multiple layers of support for projects that " +"have C and C++ extensions." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:236 +msgid "PDM support for C and C++ extensions" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:238 +msgid "" +"PDM supports using the PDM-back-end and setuptools at the same time. This" +" means that you can run setuptools to compile and build C extensions. " +"PDM's build back-end receives the compiled extension files (.so, .pyd) " +"and packages them with the pure Python files." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:244 +msgid "PDM Features" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "Feature, PDM, Notes" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "" +"When you setup PDM it allows you to select one of several build back ends" +" including: PDM-core, flit-core and hatchling. PDM also can work with " +"Meson-Python which supports move complex python builds." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "Dependency specifications" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "" +"PDM has flexible support for managing dependencies. PDM defaults to " +"using an open bound (e.g. `requests >=1.2`) approach to dependencies. " +"However you can [customize how you want to add dependencies in case you " +"prefer another approach such as that of Poetry which uses an upper bound " +"limit](https://pdm.fming.dev/latest/usage/dependency/#about-update-" +"strategy).**" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "Environment lock files" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "" +"PDM and Poetry are currently the only tools that create environment lock " +"files. Lock files are often most useful to developers creating web apps " +"where locking the environment is critical for consistent user experience." +" For community-used packages, you will likely never want to use a lock " +"file." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Environment management" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "" +"PDM provides environment management support. It supports Python virtual " +"environments, conda and a local `__pypackages__` environment which is a " +"newer option in the Python ecosystem. No extensions are needed for this " +"support." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "Select your environment type on install" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "" +"When you run `PDM init`, PDM will discover environments that are already " +"on your system and allow you to select one to use for your project." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "PDM supports publishing to both test PyPI and PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +#: ../../package-structure-code/python-package-build-tools.md:348 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Version Control based versioning" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "" +"PDM has a setuptools_scm like tool built into it which allows you to use " +"dynamic versioning that rely on git tags." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "" +"PDM supports you bumping the version of your package using standard " +"semantic version terms patch; minor; major" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +#: ../../package-structure-code/python-package-build-tools.md:304 +#: ../../package-structure-code/python-package-build-tools.md:348 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Follows current packaging standards" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "" +"PDM supports current packaging standards for adding metadata to the " +"**pyproject.toml** file." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +#: ../../package-structure-code/python-package-build-tools.md:304 +#: ../../package-structure-code/python-package-build-tools.md:348 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Install your package in editable mode" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "PDM supports installing your package in editable mode." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +#: ../../package-structure-code/python-package-build-tools.md:304 +#: ../../package-structure-code/python-package-build-tools.md:348 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Build your sdist and wheel distributions" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:251 +msgid "" +"Similar to all of the other tools PDM builds your packages sdist and " +"wheel files for you." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:264 +msgid "PDM vs. Poetry" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:265 +msgid "" +"The functionality of PDM is similar to Poetry. However, PDM also offers " +"additional, documented support for C extensions and version control based" +" versioning. As such, PDM is preferred for those working on non pure-" +"Python packages." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:269 +msgid "" +"If you are deciding between the Poetry and PDM, a smaller difference is " +"the default way that dependencies are added to your pyproject.toml file." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:271 +msgid "" +"Poetry by default follows strict semantic versioning adding dependencies " +"to your pyproject.toml file [using an upper bounds constraint " +"(`^`)](https://python-poetry.org/docs/dependency-specification/#version-" +"constraints). Upper bounds lock means that Poetry will never bump a " +"dependency to the next major version (i.e. from 1.2 to 2.0). However, you" +" can tell Poetry to use an open bound approach by explicitly adding the " +"package like this: `poetry add requests >= 1.2` rather than just using " +"`poetry add requests` which will result in a upper bound locked (ie Upper" +" bound locks means that requests 2.0 could never be installed even if it " +"came out and your package could benefit from it)." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:272 +msgid "" +"PDM defaults to open-bounds (`>=`) dependency additions which is the " +"preferred approach in the scientific python ecosystem. However, PDM also " +"allows you to specify the way dependencies are added by default. As such," +" you can also specify upper-bounds (`^`) using PDM if require that " +"approach." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:274 +msgid "" +"Finally there are some nuanced differences in how both tools create lock " +"files which we will not go into detail about here." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:277 +msgid "Challenges with PDM" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:279 +msgid "" +"PDM is a full-featured packaging tool. However it is not without " +"challenges:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:281 +msgid "" +"Its documentation can be confusing, especially if you are new to " +"packaging. For example, PDM doesn't provide an end to end beginning " +"workflow in its documentation." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:283 +msgid "" +"PDM also only has one maintainer currently. We consider individual " +"maintainer teams to be a potential risk. If the maintainer finds they no " +"longer have time to work on the project, it leaves users with a gap in " +"support. Hatch and Flit also have single maintainer teams." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:288 +msgid "" +"[You can view an example of a package that uses PDM " +"here](https://github.com/pyOpenSci/examplePy/tree/main/example4_pdm). The" +" README file for this directly provides you with an overview of what the " +"PDM command line interface looks like when you use it." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:293 +msgid "" +"[Flit is a no-frills, streamlined packaging " +"tool](https://flit.pypa.io/en/stable/) that supports modern Python " +"packaging standards. Flit is a great choice if you are building a basic " +"package to use in a local workflow that doesn't require any advanced " +"features. And if your package structure is already created. More on that " +"below." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:297 +msgid "Flit Features" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:304 +msgid "Feature, Flit, Notes" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:304 +#: ../../package-structure-code/python-package-build-tools.md:348 +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Publish to PyPI and test PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:304 +msgid "Flit supports publishing to both test PyPI and PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:304 +msgid "Helps you add metadata to your **pyproject.toml** file" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:304 +msgid "" +"Flit does support adding metadata to your **pyproject.toml** file " +"following modern packaging standards." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:304 +msgid "" +"Flit supports current packaging standards for adding metadata to the " +"**pyproject.toml** file." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:304 +msgid "Flit supports installing your package in editable mode.**" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:304 +msgid "Flit can be used to build your packages sdist and wheel distributions." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:311 +msgid "" +"NOTE: _If you are using the most current version of pip, it supports both" +" a symlink approach `flit install -s` and `python -m pip install -e .`_" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:313 +msgid "Learn more about flit" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:314 +msgid "[Why use flit?](https://flit.pypa.io/en/stable/rationale.html)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:317 +msgid "Why you might not want to use Flit" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:319 +msgid "" +"Because Flit is no frills, it is best for basic, quick builds. If you are" +" a beginner you may want to select Hatch or PDM which will offer you more" +" support in common operations." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:323 +msgid "You may NOT want to use flit if:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:325 +msgid "" +"You want to setup more advanced version tracking and management (using " +"version control for version bumping)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:326 +msgid "" +"You want a tool that handles dependency versions (use PDM or Poetry " +"instead)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:327 +msgid "You have a project that is not pure Python (Use Hatch, PDM or setuptools)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:328 +msgid "You want environment management (use PDM, Hatch or Poetry)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:333 +msgid "" +"[**Hatch**](https://hatch.pypa.io/latest/), similar to Poetry and PDM, " +"provides a unified command line interface. To separate Hatch from Poetry " +"and PDM, it also provides an environment manager for testing that will " +"make it easier for you to run tests locally across different versions of " +"Python. It also offers a nox / makefile like feature that allows you to " +"create custom build workflows such as building your documentation " +"locally. This means that you could potentially drop a tool like **Make** " +"or **Nox** from your workflow and use Hatch instead." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:340 +msgid "Hatch features" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Feature, Hatch, Notes" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "" +"Hatch is used with the backend Hatchling by default, but allows you to " +"use another backend by switching the declaration in pyproject.toml." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "" +"Currently you have to add dependencies manually with Hatch. However a " +"feature to support dependencies management may be added in a future " +"release." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "" +"Hatch supports Python virtual environments. If you wish to use other " +"types of environments such as Conda, you will need to [install a plugin " +"such as hatch-conda for conda support](https://github.com/OldGrumpyViking" +"/hatch-conda)." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Hatch supports publishing to both test PyPI and PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "" +"Hatch offers `hatch_vcs` which is a plugin that uses setuptools_scm to " +"support versioning using git tags. The workflow with `hatch_vcs` is the " +"same as that with `setuptools_scm`." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "" +"Hatch supports you bumping the version of your package using standard " +"semantic version terms patch; minor; major" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "" +"Hatch supports current packaging standards for adding metadata to the " +"**pyproject.toml** file." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "" +"Hatch will install your package into any of its environments by default " +"in editable mode. You can install your package in editable mode manually " +"using `python -m pip install -e .` Hatch mentions [editable " +"installs](https://hatch.pypa.io/latest/config/build/#dev-mode) but refers" +" to pip in its documentation." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "Hatch will build the sdist and wheel distributions" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "✨Matrix environment creation to support testing across Python versions✨" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "" +"The matrix environment creation is a feature that is unique to Hatch in " +"the packaging ecosystem. This feature is useful if you wish to test your " +"package locally across Python versions (instead of using a tool such as " +"tox)." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "" +"✨[Nox / MAKEFILE like " +"functionality](https://hatch.pypa.io/latest/environment/#selection)✨" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "" +"This feature is also unique to Hatch. This functionality allows you to " +"create workflows in the **pyproject.toml** configuration to do things " +"like serve docs locally and clean your package build directory. This " +"means you may have one less tool in your build workflow." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "✨A flexible build backend: **hatchling**✨" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:348 +msgid "" +"**The hatchling build backend offered by the maintainer of Hatch allows " +"developers to easily build plugins to support custom build steps when " +"packaging." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:362 +msgid "" +"_There is some argument about this approach placing a burden on " +"maintainers to create a custom build system. But others appreciate the " +"flexibility. The Hatch build hook approach is also comparable with the " +"features offered by PDM._" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:364 +msgid "Why you might not want to use Hatch" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:366 +msgid "" +"There are a few features that hatch is missing that may be important for " +"some. These include:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:369 +msgid "" +"Hatch doesn't support adding dependencies. You will have to add them " +"manually." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:370 +msgid "Hatch won't by default recognize Conda environments without a plugin." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:371 +msgid "" +"Similar to PDM, Hatch's documentation can difficult to work through, " +"particularly if you are just getting started with creating a package." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:372 +msgid "Hatch, similar to PDM and Flit currently only has one maintainer." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:376 +msgid "" +"[Poetry is a full-featured build tool.](https://python-poetry.org/) It is" +" also the second most popular front-end packaging tool (based upon the " +"PyPA survey). Poetry is user-friendly and has clean and easy-to-read " +"documentation." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:381 +msgid "" +"While some have used Poetry for Python builds with C/C++ extensions, this" +" support is currently undocumented. Thus, we don't recommend using Poetry" +" for more complex builds." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:385 +msgid "Poetry features" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Feature, Poetry, Notes" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "" +"Poetry helps you add dependencies to your `pyproject.toml` metadata. " +"_NOTE: currently Poetry adds dependencies using an approach that is " +"slightly out of alignment with current Python peps - however there is a " +"plan to fix this in an upcoming release._ Poetry also allows you to " +"organize dependencies in groups such as documentation, packaging and " +"tests." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Dependency specification" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "" +"Poetry allows you to be specific about version of dependencies that you " +"add to your package's pyproject.toml file. However, it's default upper " +"bound approach can be problematic for some packages (We suggest you " +"override the default setting when adding dependencies). Read below for " +"more." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "" +"Poetry allows you to either use its built in environment or you can " +"select the environment type that you want to use for managing your " +"package. [Read more about its built in environment management " +"options](https://python-poetry.org/docs/basic-usage/#using-your-virtual-" +"environment)." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Lock files" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "" +"Poetry creates a **poetry.lock** file that you can use if you need a lock" +" file for your build." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Poetry supports publishing to both test PyPI and PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "" +"The plugin [Poetry dynamic versioning](https://github.com/mtkennerly" +"/poetry-dynamic-versioning) supports versioning using git tags with " +"Poetry." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "" +"Poetry supports you bumping the version of your package using standard " +"semantic version terms patch; minor; major" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "✖✅" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "" +"Poetry does not quite support current packaging standards for adding " +"metadata to the **pyproject.toml** file but plans to fix this in an " +"upcoming release." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "" +"Poetry supports installing your package in editable mode using " +"`--editable`" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:392 +msgid "Poetry will build your sdist and wheel distributions using `poetry build`" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:407 +msgid "Challenges with Poetry" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:409 +msgid "Some challenges of Poetry include:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:411 +msgid "" +"Poetry, by default, pins dependencies using an \"upper bound\" limit " +"specified with the `^` symbol by default. However, this behavior can be " +"over-written by specifying the dependency when you use `Poetry add` as " +"follows: `poetry add \"requests>=2.1\"` See breakout below for more " +"discussion on issues surrounding upper-bounds pinning." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:412 +msgid "" +"_Minor Challenge:_ The way Poetry currently adds metadata to your " +"pyproject.toml file does not follow current Python standards. However, " +"this is going to be addressed with Poetry release version 2.0." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:414 +msgid "" +"Poetry is an excellent tool. Use caution when using it to pin " +"dependencies as Poetry's approach to pinning can be problematic for many " +"builds. If you use Poetry, we strongly suggest that you override the " +"default upper bound dependency option." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:420 +msgid "Challenges with Poetry dependency pinning" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:423 +msgid "" +"By default, Poetry pins dependencies using `^` by default. This `^` " +"symbol means that there is an \"upper bound\" to the dependency. Thus " +"poetry won't bump a dependency version to a new major version. Thus, if " +"your package uses a dependency that is at version 1.2.3, Poetry will " +"never bump the dependency to 2.0 even if there is a new major version of " +"the package. Poetry will instead bump up to 1.9.x." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:429 +msgid "" +"Poetry does this because it adheres to strict semantic versioning which " +"states that a major version bump (from 1.0 to 2.0 for example) means " +"there are breaking changes in the tool. However, not all tools follow " +"strict semantic versioning. [This approach has been found to be " +"problematic by many of our core scientific " +"packages.](https://iscinumpy.dev/post/bound-version-constraints/)" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:434 +msgid "" +"This approach also won't support others ways of versioning tools, for " +"instance, some tools use [calver](https://calver.org/) which creates new " +"versions based on the date." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:438 +msgid "Using Setuptools Back-end for Python Packaging with Build Front-end" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:440 +msgid "" +"[Setuptools](https://setuptools.pypa.io/en/latest/) is the most mature " +"Python packaging build tool with [development dating back to 2009 and " +"earlier](https://setuptools.pypa.io/en/latest/history.html#). Setuptools " +"also has the largest number of community users (according to the PyPA " +"survey). Setuptools does not offer a user front-end like Flit, Poetry and" +" Hatch offer. As such you will need to use other tools such as **build** " +"to create your package distributions and **twine** to publish to PyPI." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:448 +msgid "" +"While setuptools is the most commonly used tool, we encourage package " +"maintainers to consider using a more modern tool for packaging such as " +"Poetry, Hatch or PDM." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:451 +msgid "" +"We discuss setuptools here because it's commonly found in the ecosystem " +"and contributors may benefit from understanding it." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:454 +msgid "Setuptools Features" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:456 +msgid "Some of features of setuptools include:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:458 +msgid "Fully customizable build workflow" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:459 +msgid "Many scientific Python packages use it." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:460 +msgid "" +"It offers version control based package versioning using " +"**setuptools_scm**" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:461 +msgid "It supports modern packaging using **pyproject.toml** for metadata" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:462 +msgid "Supports backwards compatibly for older packaging approaches." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:464 +msgid "Challenges using setuptools" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:468 +msgid "Setuptools has a few challenges:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:470 +msgid "" +"Setuptools does not support interactive features such as auto / tab " +"completion by default if you are working in an IDE like VSCODE and using " +"an editable install for development. [See notes here about pylance " +"support](https://github.com/microsoft/pylance-" +"release/blob/main/TROUBLESHOOTING.md#editable-install-modules-not-found)." +" In comparison, tools such as flit, hatch, PDM support interactive " +"features such as tab / auto completion when using an IDE like VSCODE or " +"pycharm (as long as your version of pip is current!)." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:471 +msgid "" +"Because **setuptools** has to maintain backwards compatibility across a " +"range of packages, it is not as flexible in its adoption of modern Python" +" packaging standards." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:474 +msgid "" +"The above-mentioned backwards compatibility makes for a more complex " +"code-base." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:475 +msgid "" +"Your experience as a user will be less streamlined and simple using " +"setuptools compared to other tools discussed on this page." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:477 +msgid "" +"There are also some problematic default settings that users should be " +"aware of when using setuptools. For instance:" +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:480 +msgid "" +"setuptools will build a project without a name or version if you are not " +"using a **pyproject.toml** file to store metadata." +msgstr "" + +#: ../../package-structure-code/python-package-build-tools.md:482 +msgid "" +"setuptools also will include all of the files in your package repository " +"if you do not explicitly tell it to exclude files using a **MANIFEST.in**" +" file" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:1 +msgid "Learn about Building a Python Package" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:8 +msgid "" +"Once you have published both package distributions (the source " +"distribution and the wheel) to PyPI, you can then publish to conda-forge." +" conda-forge requires an source distribution on PyPI in order to build " +"your package on conda-forge. You do not need to rebuild your package to " +"publish to conda-forge." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:11 +msgid "" +"You need to build your Python package in order to publish it to PyPI (or " +"a conda channel). The build process organizes your code and metadata into" +" a distribution format that can be uploaded to PyPI and subsequently " +"downloaded and installed by users. NOTE: you need to publish a sdist to " +"PyPI in order for conda-forge to properly build your package " +"automatically." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:14 +msgid "What is building a Python package?" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:16 +msgid "" +"To [publish your Python package](publish-python-package-pypi-conda) and " +"make it easy for anyone to install, you first need to build it." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:18 +msgid "But, what does it mean to build a Python package?" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:20 +msgid "" +"[As shown in the figure above](#pypi-conda-channels), when you build your" +" Python package, you convert the source files into something called a " +"distribution package. A distribution package contains your source code " +"and metadata about the package, in the format required by the Python " +"Package Index, so that it can be installed by tools like pip." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:23 +msgid "" +"The term package used to mean many different things in Python and other " +"languages. On this page, we adapt the convention of the [Python Packaging" +" Authority](https://www.pypa.io/en/latest/) and refer to the product of " +"the build step as a **distribution package**." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:27 +msgid "" +"This process of organizing and formatting your code, documentation, tests" +" and metadata into a format that both pip and PyPI can use, is called a " +"build step." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:31 +msgid "Project metadata and PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:33 +msgid "" +"The metadata that both build tools and PyPI uses to describe and " +"understand your package is generally stored in a [pyproject.toml file" +"](pyproject-toml-python-package-metadata). This metadata is used for " +"several purposes:" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:35 +msgid "" +"It helps whatever tool you use to build your package (pip, [pypa's " +"Build](https://pypi.org/project/build/) or an end-to-end tool such as " +"poetry, PDM or Hatch) understand how to build your package. Information " +"it provides to your build tool includes:" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:37 +msgid "" +"The `[build-system]` table in your pyproject.toml file tells pip what " +"[build backend tool](build_backends) you wish to use for creating your " +"sdist and wheel distributions." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:45 +msgid "" +"And the dependencies section of your project table tells the build tool " +"and PyPI what dependencies your project requires." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:54 +msgid "" +"When the build tool creates your package distribution file (the file that" +" you publish on PyPI), it also creates a METADATA file which PyPI can " +"read and use to help users find your package. For example:" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:56 +msgid "" +"The `classifiers = ` section of your `[project]` table in the " +"pyproject.toml file provides information that users on PyPI can use to " +"filter for packages that contain specific licenses or that support " +"specific versions of python." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:73 +msgid "What happened to setup.py and setup.cfg for metadata?" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:76 +msgid "" +"Project metadata used to be stored in either a setup.py file or a " +"setup.cfg file. The current recommended practice for storing package " +"metadata is to use a pyproject.toml file. [Learn more about the " +"pyproject.toml file here.](pyproject-toml-python-package-metadata)" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:79 +msgid "An example - xclim" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:94 +msgid "" +"Graphic showing the high level packaging workflow. On the left you see a " +"graphic with code, metadata and tests in it. those items all go into your" +" package. Documentation and data are below that box because they aren't " +"normally published in your packaging wheel distribution. an arrow to the " +"right takes you to a build distribution files box. that box leads you to " +"either publishing to TestPyPI or the real PyPI. from PyPI you can then " +"connect to conda-forge for an automated build that sends distributions " +"from PyPI to conda-forge." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:96 +msgid "" +"You need to build your Python package in order to publish it to PyPI (or " +"Conda). The build process organizes your code and metadata into a " +"distribution format that can be uploaded to PyPI and subsequently " +"downloaded and installed by users. NOTE: you need to publish a sdist to " +"PyPI in order for conda-forge to properly build your package " +"automatically." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:101 +msgid "" +"This screenshot shows the metadata on PyPI for the xclim package. on it " +"you can see the name of the license, the author and maintainer names " +"keywords associated with the package and the base python version it " +"requires which is 3.8." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:103 +msgid "PyPI screenshot showing metadata for the xclim package." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:110 +msgid "" +"Here you see the maintinaer metadata as it is displayed on PyPI. for " +"xclim there are three maintainers listed with their profile pictures and " +"github user names to the right." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:112 +msgid "" +"Maintainer names and GitHub usernames for the xclim package as they are " +"displayed on PyPI. This information is recorded in your pyproject.toml " +"and then processed by your build tool and stored in your packages sdist " +"and wheel distributions." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:115 +msgid "How to create the distribution format that PyPI and Pip expects?" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:117 +msgid "" +"You could in theory create your own scripts to organize your code the way" +" PyPI wants it to be. However, just like there are packages that handle " +"known structures such as Pandas for data frames and Numpy for arrays, " +"there are packages and tools that help you create package build " +"distribution files." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:121 +msgid "" +"There are a suite of packaging tools that can either help you with the " +"entire packaging process or just one step of the process. For instance " +"setuptools is a commonly used build back end that can be used to create " +"your sdist and wheel. Whereas tools like Hatch, PDM, Poetry and flit help" +" with other parts of the packaging process." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:127 +msgid "" +"While this can cause some confusion and complexity in the packaging " +"ecosystem - for the most part, each tool provides the same distribution " +"output (with minor differences that most users may not care about). Learn" +" more about those tools on this page." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:133 +msgid "" +"Below, you will learn about the two distribution files that PyPI expects " +"you to publish: sdist and wheel. You will learn about their structure and" +" what files belong in each." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:136 +msgid "" +"There are two core distribution files that you need to create to publish " +"your Python package to PyPI source distribution (often called an sdist) " +"and wheel. The sdist contains the raw source code for your package. The " +"wheel (.whl) contains the built / compiled files that can be directly " +"installed onto anyones' computer." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:142 +msgid "Learn more about both distributions below." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:145 +msgid "" +"If your package is a pure python package with no additional build / " +"compilation steps then the sdist and wheel distributions will have " +"similar content. However if your package has extensions in other " +"languages or is more complex in its build, the two distributions will be " +"very different." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:150 +msgid "" +"Also note that we are not discussing conda build workflows in this " +"section. [You can learn more about conda builds " +"here.](https://conda.io/projects/conda-build/en/latest/user-" +"guide/tutorials/index.html)" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:155 +msgid "Source Distribution (sdist)" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:157 +msgid "" +"**Source files** are the unbuilt files needed to build your package. " +"These are the \"raw / as-is\" files that you store on GitHub or whatever " +"platform you use to manage your code." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:161 +msgid "" +"Source Distributions (**S** + **Dist**) are referred to as sdist. As the " +"name implies, a SDIST contains the source code; it has not been built or " +"compiled in any way. Thus, when a user installs your source distribution " +"using pip, pip needs to run a build step first. For this reason, you " +"could define a source distribution as a compressed archive that contains " +"everything required to build a wheel (except for project dependencies) " +"without network access." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:165 +msgid "" +"Sdist is normally stored as a `.tar.gz` archive (often called a " +"\"tarball\"). Thus, when a user installs your source distribution using " +"pip, pip needs to run a build step first." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:167 +msgid "Below is an example sdist for the stravalib Python package:" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:219 +msgid "GitHub archive vs sdist" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:221 +msgid "" +"When you make a release on GitHub, it creates a `git archive` that " +"contains all of the files in your GitHub repository. While these files " +"are similar to an sdist, these two archives are not the same. The sdist " +"contains a few other items including a metadata directory and if you use " +"`setuptools_scm` or `hatch_vcs` the sdist may also contain a file that " +"stores the version." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:229 +msgid "Wheel (.whl files):" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:231 +msgid "" +"A wheel file is a ZIP-format archive whose filename follows a specific " +"format (below) and has the extension `.whl`. The `.whl` archive contains " +"a specific set of files, including metadata that are generated from your " +"project's pyproject.toml file. The pyproject.toml and other files that " +"may be included in source distributions are not included in wheels " +"because it is a built distribution." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:238 +msgid "" +"The wheel (.whl) is your built binary distribution. **Binary files** are " +"the built / compiled source files. These files are ready to be installed." +" A wheel (**.whl**) is a **zip** file containing all of the files needed " +"to directly install your package. All of the files in a wheel are " +"binaries - this means that code is already compiled / built. Wheels are " +"thus faster to install - particularly if you have a package that requires" +" build steps." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:240 +msgid "" +"The wheel does not contain any of your package's configuration files such" +" as **setup.cfg** or **pyproject.toml**. This distribution is already " +"built so it's ready to install." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:244 +msgid "" +"Because it is built, the wheel file will be faster to install for pure " +"Python projects and can lead to consistent installs across machines." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:252 +msgid "" +"Wheels are also useful in the case that a package needs a **setup.py** " +"file to support a more complex build. In this case, because the files in " +"the wheel bundle are pre built, the user installing doesn't have to worry" +" about malicious code injections when it is installed." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:259 +msgid "The filename of a wheel contains important metadata about your package." +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:261 +msgid "Example: **stravalib-1.1.0.post2-py3-none.whl**" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:263 +msgid "name: stravalib" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:264 +msgid "version: 1.1.0" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:265 +msgid "" +"build-number: 2 (post2) [(read more about post " +"here)](https://peps.python.org/pep-0440/#post-release-separators)" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:266 +msgid "py3: supports Python 3.x" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:267 +msgid "none: is not operating system specific (runs on windows, mac, linux)" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:268 +msgid "any: runs on any computer processor / architecture" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:270 +msgid "What a wheel file looks like when unpacked (unzipped):" +msgstr "" + +#: ../../package-structure-code/python-package-distribution-files-sdist-wheel.md:304 +msgid "[Read more about the wheel format here](https://pythonwheels.com/)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:1 +msgid "Python Package Structure for Scientific Python Projects" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:3 +msgid "" +"There are two different layouts that you will commonly see within the " +"Python packaging ecosystem: [src and flat " +"layouts.](https://packaging.python.org/en/latest/discussions/src-layout-" +"vs-flat-layout/) 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](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 be tremendous 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:23 +msgid "An example of the **src/package** layout structure can be seen below." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:45 +msgid "Note the location of the following directories in the example above:" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:47 +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 of the **src/** folder." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:48 +msgid "" +"**tests/** this directory contains the tests for your project code. In a " +"**src/** layout tests are normally included at the same directory level " +"of the **src/** folder." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:49 +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:51 +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:55 +msgid "CHANGELOG.md" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:56 +msgid "CODE_OF_CONDUCT.md" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:57 +msgid "CONTRIBUTING.md" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:58 +msgid "LICENSE.txt" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:59 +msgid "README.md" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:63 +msgid "Click here to read about our packaging documentation requirements." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:70 +msgid "" +"While we recommend the **src/** layout we also review the **flat** layout" +" here. Both are used in the Python ecosystem." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:72 +msgid "Example scientific packages that use **src/package** layout" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:74 +msgid "[Sourmash](https://github.com/sourmash-bio/sourmash)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:75 +msgid "[bokeh](https://github.com/bokeh/bokeh)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:76 +msgid "[openscm](https://github.com/openscm/openscm-runner)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:77 +msgid "[awkward](https://github.com/scikit-hep/awkward)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:78 +msgid "[poliastro](https://github.com/poliastro/poliastro/)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:82 +msgid "The src/ layout and testing" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:84 +msgid "" +"The benefit of using the **src/package** layout, particularly if you are " +"creating a new package, 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, you may be missing issues that users encounter when " +"your package is installed." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:91 +msgid "" +"If `tests/` are outside of the **src/package** directory, they aren't " +"included in the package wheel. This makes your package size slightly " +"smaller which then places places a smaller storage burden on PyPI which " +"has over 400,000 packages to support." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:93 +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:95 +msgid "How Python discovers and prioritizes importing modules" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:97 +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:99 +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:101 +msgid "" +"However, if your package lives in a src/ directory structure " +"**src/package** then it won't be, by default, added to the Python path. " +"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:103 +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:106 +msgid "Sometimes tests are needed in a distribution" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:108 +msgid "" +"We do not recommend including tests as part of your package 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 is functioning correctly 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:117 +msgid "" +"Including the **tests/** directory in your **src/package** directory " +"ensures that tests will be included in your package's wheel." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:119 +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:121 +msgid "Challenges with including tests and data in a package wheel" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:124 +msgid "" +"Tests, especially when accompanied by test data can create a few small " +"challenges including:" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:126 +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:127 +msgid "Large file sizes can also slow down package install." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:129 +msgid "" +"However, in some cases, particularly in the scientific Python ecosystems " +"you may need to include tests." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:132 +msgid "**Don't include test suite datasets in your package**" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:134 +msgid "" +"If you do 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:140 +msgid "" +"Check out the testing section of our guide for more information about " +"tests." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:142 +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:146 +msgid "" +"If your package tests require data, we suggest that you do NOT include " +"that data within your package structure. We will discuss this in more " +"detail in a tutorial. Include 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:153 +msgid "About the flat Python package layout" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:155 +msgid "Currently most scientific packages use the **flat-layout** given:" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:157 +msgid "" +"It's the most commonly found layout with the scientific Python ecosystem " +"and people tend to look to other packages / maintainers that they respect" +" for examples of how to build Python packages." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:160 +msgid "" +"Many Python tools depend upon tools in other language and / or complex " +"builds with compilation steps. Many developers thus appreciate / are used" +" to features of the flat layout." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:164 +msgid "" +"While we present this layout here in our guide, we suggest that those " +"just getting started with python packaging start with the src/package " +"layout discussed above. Numerous packages in the ecosystem [have had to " +"move to a src/ layout](https://github.com/scikit-build/cmake-python-" +"distributions/pull/145)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:169 +msgid "Why most scientific Python packages do not use source" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:172 +msgid "" +"In most cases the advantages of using the **src/package** layout for " +"larger scientific packages that already use flat approach are not worth " +"it. Moving from a flat layout to a **src/package** layout would come at a" +" significant cost to maintainers." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:177 +msgid "" +"However, the advantages of using the **src/package** layout for a " +"beginner are significant. As such, we recommend that if you are getting " +"started with creating a package, that you consider using a " +"**src/package** layout." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:182 +msgid "What does the flat layout structure look like?" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:184 +msgid "The flat layout's primary characteristics are:" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:186 +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:188 +msgid "" +"Often the `tests/` directory also lives within that same `package` " +"directory." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:190 +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:212 +msgid "Benefits of using the flat layout in your Python package" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:214 +msgid "" +"There are some benefits to the scientific community in using the flat " +"layout." +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:216 +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:218 +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:224 +msgid "Core scientific Python packages that use the flat layout" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:227 +msgid "[numpy](https://github.com/numpy/numpy)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:228 +msgid "[scipy](https://github.com/scipy/scipy)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:229 +msgid "[pandas](https://github.com/pandas-dev/pandas)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:230 +msgid "[xarray](https://github.com/pydata/xarray)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:231 +msgid "[Jupyter-core](https://github.com/jupyter/jupyter_core)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:232 +msgid "[Jupyter notebook](https://github.com/jupyter/notebook)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:233 +msgid "[scikit-learn](https://github.com/scikit-learn/scikit-learn)" +msgstr "" + +#: ../../package-structure-code/python-package-structure.md:235 +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 is not worth the maintenance investment." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:1 +msgid "Creating New Versions of Your Python Package" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:6 +msgid "Key Takeways" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:8 +msgid "" +"Follow [semantic versioning guidelines (SemVer) " +"rules](https://semver.org/) when bumping (increasing) your Python's " +"package version; for example a major version bump (version 1.0 --> 2.0) " +"equates to breaking changes in your package's code for a user." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:9 +msgid "" +"You may want to consider using a plugin like hatch_vsc for managing " +"versions of your package - if you want to have a GitHub only release " +"workflow." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:10 +msgid "" +"Otherwise most major package build tools such as Hatch, Flit and PDM have" +" a version feature that will help you update your package's version" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:11 +msgid "Avoid updating your packages version number manually by hand in your code!" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:14 +msgid "" +"pyOpenSci recommends that you follow the [Python PEP " +"440](https://peps.python.org/pep-0440) which recommends using [semantic " +"versioning guidelines](https://www.python.org/dev/peps/pep-0440" +"/#semantic-versioning) when assigning release values to new versions of " +"your Python package." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:18 +msgid "" +"[Semantic versioning](https://semver.org/) is an approach to updating " +"package versions that considers the type and extent of a change that you " +"are making to the package code. Being consistent with how and when you " +"update your package versions is important as:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:23 +msgid "" +"It helps your users (which might include other developers that depend on " +"your package) understand the extent of changes to a package." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:24 +msgid "" +"It helps your development team make decisions about when to bump a " +"package version based on standard rules." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:26 +msgid "" +"Consistent version increases following semver rules mean that values of " +"your package version explain the extent of the changes made in the code " +"base from version to version. thus your package version numbers become " +"\"expressive\" in the same way that naming code variables well can [make " +"code expressive](https://medium.com/@daniel.oliver.king/writing-" +"expressive-code-b69ef7a5a2fa)." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:28 +msgid "A note about versioning" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:29 +msgid "" +"In some cases even small version changes can turn a package update into a" +" breaking change for some users. What is also important is that you " +"document how you version your code and if you can, also document your " +"deprecation policy for code." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:37 +msgid "SemVer rules" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:39 +msgid "Following SemVer, your bump your package version to a:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:41 +msgid "patch (1.1.1 --> 1.1.**2**)" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:42 +msgid "minor (1.1.1 --> 1.**2**.1)" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:43 +msgid "major (1.1.1 --> **2**.1.1)" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:45 +msgid "version number change based on the following rules:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:47 +msgid "Given a version number MAJOR.MINOR.PATCH, increment the:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:49 +msgid "**MAJOR version** when you make incompatible API changes" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:50 +msgid "" +"**MINOR version** when you add functionality in a backwards compatible " +"manner" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:51 +msgid "" +"**PATCH version** when you make backwards compatible bug fixes Additional" +" labels for pre-release and build metadata are available as extensions to" +" the MAJOR.MINOR.PATCH format." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:56 +msgid "" +"Some people prefer to use [calver](https://calver.org/index.html) for " +"versioning. It may be a simpler-to-use system given it relies upon date " +"values associated with released versions. However, calver does not " +"provide a user with a sense of when a new version might break an existing" +" build. As such we still suggest semver." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:59 +msgid "" +"pyOpenSci will never require semver in a peer review as long as a package" +" has a reasonable approach to versioning!" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:63 +msgid "Avoid manually updating Python package version numbers if you can" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:65 +msgid "" +"Often times you may want to have your package version value in multiple " +"locations. One example of this is that it might be both an attribute in " +"your package **version** and also called in your documentation." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:70 +msgid "" +"We recommend that you avoid manual updates of your package version number" +" to avoid human-error. It is better practice to keep your version number " +"in one location." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:74 +msgid "" +"If you can't implement a single location version, then consider using a " +"tool like hatch, PDM or bump2version that will update the version values " +"for you - throughout your package." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:78 +msgid "" +"Below we discuss some tools that you can use to manage updating Python " +"package versions." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:83 +msgid "Tools to manage versions for your Python package" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:85 +msgid "" +"There are a handful of tools that are widely used in the scientific " +"ecosystem that you can use to manage your package versions. Some of these" +" tools are built into or work with your chosen [packaging build tools " +"that discussed in this chapter.](python-package-build-tools)" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:91 +msgid "Below, we provide an overview of these tools." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:97 +msgid "" +"There are three general groups of tools that you can use to manage " +"package versions:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:100 +msgid "" +"**semantic release tools:** These tools will automagically determine what" +" type of version bump to use using the text in your commit messages. " +"Below we discuss [Python Semantic Release](https://python-semantic-" +"release.readthedocs.io/en/latest/) as a Python tool that implements a " +"semantic versioning approach." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:102 +msgid "" +"**Manual incremental bump tools:** Tools like " +"[Hatch](https://hatch.pypa.io/latest/version/) offer version bumping " +"within your package. Normally this is implemented at the command link for" +" instance `hatch version major` would bump your project from 0.x to 1.0." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:103 +msgid "" +"**Version Control System tools:** Finally there are tools that rely on " +"your version control system to track versions. These tools often are " +"plugins to your package build tool (ex: setuptools build or hatchling). " +"We discuss this option below assuming that you are using **.git tags** " +"and **GitHub** to manage your package repository." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:105 +msgid "Semantic release, vs version control based vs manual version bumping" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:107 +msgid "" +"Generally semantic release and version control system tools can be setup " +"to run automatically on GitHub using GitHub actions. This means that you " +"can create a workflow where a GitHub release and associated new version " +"tag is used to trigger an automated build that:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:113 +msgid "Builds your package and updates the version following the new tag" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:114 +msgid "Tests the build and publishes to test PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:115 +msgid "Publishes the package to PyPI" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:118 +msgid "" +"Bumping a package version refers to the step of increasing the package " +"version after a set number of changes have been made to it. For example, " +"you might bump from version 0.8 to 0.9 of a package. or from 0.9 to 1.0." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:122 +msgid "" +"Using semantic versioning, there are three main \"levels\" of versions " +"that you might consider:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:125 +msgid "Major, minor and patch. These are described in more detail below." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:128 +msgid "Tools for bumping Python package versions" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:130 +msgid "" +"In this section we discuss the following tools for managing your Python " +"package's version:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:133 +msgid "hatch &" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:134 +msgid "hatch_vcs plugin for hatchling" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:135 +msgid "setuptools-scm" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:136 +msgid "python-semantic-version" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:138 +msgid "Tool 1: Hatch and other build tools that offer incremental versioning" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:140 +msgid "" +"Many of the modern build tool front end tools offer version support that " +"follow semantic versioning rules. These tools are different from Python " +"Semantic Version in that they do not require specific commit messages to " +"implement version. Rather, they allow you to update the version at the " +"command line using commands such as:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:146 +msgid "`tool-name version update major`" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:147 +msgid "`tool-name version update minor`" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:149 +msgid "" +"[Hatch](https://hatch.pypa.io/latest/version/), for instance offers " +"`hatch version minor` which will modify the version of your package " +"incrementally. With **Hatch** the version value will be found in your " +"`pyproject.toml` file. " +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:152 +msgid "Hatch (or other tools like PDM) Pros" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:154 +msgid "Easy to use version updates locally using a single tool!" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:156 +msgid "Hatch (or other tools like PDM) Cons" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:158 +msgid "" +"There will be some setup involved to ensure package version is updated " +"throughout your package" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:160 +msgid "Tool 2: Hatch_vcs & hatchling build back-end" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:162 +msgid "" +"[hatch_vcs](https://github.com/ofek/hatch-vcs) is a versioning tool that " +"allows you to manage package versions using **git tags**. Hatch_vcs " +"creates a **\\_version.py** file in your package ecosystem that keeps " +"track of the package's current version." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:167 +msgid "" +"Hatch keeps track of your package's version in a `_version.py` file. " +"Storing the version in a single file managed by Hatch provides your " +"package with a \"single source of truth\" value for the version number. " +"This in turn eliminates potential error associated with manually updating" +" your package's version." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:173 +msgid "" +"When you (or your CI system) build your package, hatch checks the current" +" tag number for your package. if it has increased, it will update the " +"**\\_version.py** file with the new value." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:176 +msgid "" +"Thus, when you create a new tag or a new release with a tag and build " +"your package, Hatch will access the new tag value and use it to update " +"your package version." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:179 +msgid "" +"To use **hatch_vcs** you will need to use the **hatchling** build back " +"end." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:182 +msgid "" +"Hatchling can also be used with any of the modern build tools including " +"**Flit** and **PDM** if you prefer those for your day to day workflow." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:187 +msgid "Hatch example setup in your pyproject.toml" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:196 +msgid "" +"**Hatch_vcs** supports a fully automated package release and build, and " +"push to PyPI workflow on GitHub." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:206 +msgid "" +"If you use **setuptools_scm**, then you might find **hatch_vcs** and " +"**hatchling** to be the modern equivalent to your current setuptools / " +"build workflow." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:209 +msgid "hatch_vcs Pros" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:211 +msgid "Hatch supports modern Python packaging standards" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:212 +#: ../../package-structure-code/python-package-versions.md:238 +msgid "It creates a single-source file that contains your package version." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:213 +#: ../../package-structure-code/python-package-versions.md:239 +msgid "You never manually update the package version" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:214 +#: ../../package-structure-code/python-package-versions.md:240 +msgid "" +"You can automate writing the version anywhere in your package including " +"your documentation!" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:215 +#: ../../package-structure-code/python-package-versions.md:241 +msgid "" +"It supports a purely GitHub based release workflow. This simplifies " +"maintenance workflows." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:216 +#: ../../package-structure-code/python-package-versions.md:242 +msgid "" +"Version number is updated in your package via a hidden `_version.py` " +"file. There is no manual configuration updates required." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:217 +#: ../../package-structure-code/python-package-versions.md:243 +msgid "" +"While we like detailed commit messages (See Python Semantic Version " +"below), we know that sometimes when maintaining a package specific " +"guidelines around commit messages can be hard to apply and manage." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:219 +msgid "hatch_vcs Cons" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:221 +msgid "" +"In a CI workflow you will end up manually entering or creating the " +"version number via a tag on GitHub. But you could locally develop a build" +" to \"bump\" tag versions" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:224 +msgid "Tool 3: setuptools-scm versioning using git tags" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:226 +msgid "" +"[`Setuptools_scm`](https://github.com/pypa/setuptools_scm/) is an " +"extension that you can use with setuptools to manage package versions. " +"**Setuptools_scm** operates the same way that **hatch_vcs** (discussed " +"above) does. It stores a version in a **\\_version.py** file and relies " +"on (**git**) tags to determine the package's current version." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:232 +msgid "" +"If you are using **setuptools** as your primary build tool, then " +"`*setuptools-scm` is a good choice as:" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:236 +msgid "setuptools_scm Pros" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:244 +msgid "**setuptools** is still the most commonly used Python packaging build tool" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:246 +msgid "setuptools_scm Cons" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:248 +msgid "" +"In a CI workflow you will end up manually entering or creating the " +"version number via a tag on GitHub." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:249 +msgid "Not well documented" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:250 +msgid "" +"Because setuptools will always have to support backwards compatibility it" +" will always be slower in adopting modern Python packaging conventions." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:252 +msgid "" +"As such you might consider using a more modern tool such as **hatch_vcs**" +" and **hatchling** to build your package and manage package versions." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:264 +msgid "" +"Tool 4: [Python semantic release](https://python-semantic-" +"release.readthedocs.io/en/latest/)" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:266 +msgid "" +"Python semantic release uses a commit message workflow that updates the " +"version of your package based on keywords found in your commit messages. " +"As the name implies, Python Semantic Release follows semver release " +"rules." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:271 +msgid "" +"With Python Semantic Release, versions are triggered using specific " +"language found in a git commit message." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:274 +msgid "" +"For example, the words `fix(attribute_warning):` trigger Python Semantic " +"Release to implement a **patch** version bump. For instance if your " +"package was at version 1.1.0 and you made the commit below with the words" +" fix(text-here), Python Semantic Release would bump your package to " +"version 1.1.1." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:284 +msgid "" +"Similarly a feature (`feat()`) triggers a minor version bump. For example" +" from version 1.1 to version 1.2" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:292 +msgid "" +"You can find a thoughtful discussion of python semantic version [in this " +"Python package guide](https://py-pkgs.org/07-releasing-versioning" +"#automatic-version-bumping). Note that the guide hasn't been updated " +"since 2020 and will potentially be updated in the future! But for now, " +"some of the commands are dated but the content is still excellent." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:295 +msgid "Python Semantic Release Pros" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:297 +msgid "Follows semver versioning closely" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:298 +msgid "" +"Enforces maintainers using descriptive commit messages which can simplify" +" troubleshooting and ensure a cleaner and more self-describing git " +"history." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:300 +msgid "Python Semantic Release Cons" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:302 +msgid "" +"Requires very specific commit language to work. In practice some " +"maintainers and contributors may not be able to maintain that level of " +"specificity in commit messages (NOTE: there are bots that will check git " +"commit messages in a repo)" +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:303 +msgid "" +"Release happens at the command line. This makes is harder to implement a " +"GitHub based release workflow as the wrong commit message could trigger a" +" release." +msgstr "" + +#: ../../package-structure-code/python-package-versions.md:304 +msgid "" +"The version number is manually updated in a configuration file such as " +"`pyproject.toml` vs. in a package **\\_version.py** file." +msgstr "" diff --git a/locales/es/LC_MESSAGES/tutorials.po b/locales/es/LC_MESSAGES/tutorials.po new file mode 100644 index 00000000..3427e46d --- /dev/null +++ b/locales/es/LC_MESSAGES/tutorials.po @@ -0,0 +1,5417 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2024, pyOpenSci +# This file is distributed under the same license as the pyOpenSci Python +# Package Guide package. +# FIRST AUTHOR , 2024. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: pyOpenSci Python Package Guide \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-06-28 08:42-0400\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: es\n" +"Language-Team: es \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.15.0\n" + +#: ../../tutorials/add-license-coc.md:1 +msgid "Add a `LICENSE` & `CODE_OF_CONDUCT` to your Python package" +msgstr "" + +#: ../../tutorials/add-license-coc.md:3 +msgid "In the [previous lesson](add-readme) you:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:5 +msgid "" +" " +"Created a basic `README.md` file for your scientific Python package" +msgstr "" + +#: ../../tutorials/add-license-coc.md:7 +msgid "" +" " +"Learned about the core components that are useful to have in a `README` " +"file." +msgstr "" + +#: ../../tutorials/add-license-coc.md:9 ../../tutorials/add-readme.md:10 +msgid "Learning objectives" +msgstr "" + +#: ../../tutorials/add-license-coc.md:12 ../../tutorials/add-readme.md:12 +#: ../../tutorials/installable-code.md:41 ../../tutorials/pyproject-toml.md:22 +#: ../../tutorials/setup-py-to-pyproject-toml.md:15 +msgid "In this lesson you will learn:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:14 +msgid "" +"How to select a license and add a `LICENSE` file to your package " +"repository, with a focus on the GitHub interface." +msgstr "" + +#: ../../tutorials/add-license-coc.md:15 +msgid "How to add a `CODE_OF_CONDUCT` file to your package repository." +msgstr "" + +#: ../../tutorials/add-license-coc.md:16 +msgid "" +"How you can use the Contributors Covenant website to add generic language" +" as a starting place for your `CODE_OF_CONDUCT`." +msgstr "" + +#: ../../tutorials/add-license-coc.md:19 +msgid "What is a license?" +msgstr "" + +#: ../../tutorials/add-license-coc.md:21 +msgid "" +"A license contains legal language about how users can use and reuse your " +"software. To set the `LICENSE` for your project, you:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:23 +msgid "" +"create a `LICENSE` file in your project directory that specifies the " +"license that you choose for your package and" +msgstr "" + +#: ../../tutorials/add-license-coc.md:24 +msgid "reference that file in your `pyproject.toml` data where metadata are set." +msgstr "" + +#: ../../tutorials/add-license-coc.md:26 +msgid "" +"By adding the `LICENSE` file to your `pyproject.toml` file, the `LICENSE`" +" will be included in your package's metadata which is used to populate " +"your package's PyPI landing page. The `LICENSE` is also used in your " +"GitHub repository's landing page interface." +msgstr "" + +#: ../../tutorials/add-license-coc.md:28 +msgid "What license should you use?" +msgstr "" + +#: ../../tutorials/add-license-coc.md:30 +msgid "" +"We suggest that you use a permissive license that accommodates the other " +"most commonly used licenses in the scientific Python ecosystem (MIT[^mit]" +" and BSD-3[^bsd3]). If you are unsure, use MIT given it's the generally " +"recommended license on [choosealicense.com](https://choosealicense.com/)." +msgstr "" + +#: ../../tutorials/add-license-coc.md:33 +msgid "Licenses for the scientific Python ecosystem" +msgstr "" + +#: ../../tutorials/add-license-coc.md:34 +msgid "" +"[We discuss licenses for the scientific Python ecosystem in more detail " +"here in our guidebook.](../documentation/repository-files/license-files)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:37 +msgid "Where should the `LICENSE` file live" +msgstr "" + +#: ../../tutorials/add-license-coc.md:39 +msgid "" +"Your `LICENSE` file should be placed at the root of your package's " +"repository. When you add the `LICENSE` at the root, GitHub will " +"automagically discover it and provide users with a direct link to your " +"`LICENSE` file within your GitHub repository." +msgstr "" + +#: ../../tutorials/add-license-coc.md:45 +msgid "" +"Image showing the GitHub repository for SunPy an accepted pyOpenSci " +"package." +msgstr "" + +#: ../../tutorials/add-license-coc.md:47 +msgid "" +"Notice at the top of the README portion of the GitHub landing page, there" +" are three tabs directly linking to the `README` file which is visible, " +"the `CODE_OF_CONDUCT` file and one that specifies the license that SunPy " +"uses. These files are discovered by GitHub because they are placed in the" +" root of the project directory using standard naming conventions." +msgstr "" + +#: ../../tutorials/add-license-coc.md:54 +msgid "How to add a `LICENSE` file to your package directory" +msgstr "" + +#: ../../tutorials/add-license-coc.md:56 +msgid "There are several ways to add a `LICENSE` file:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:58 +msgid "" +"When you create a new repository on GitHub, it will ask you if you wish " +"to add a `LICENSE` file at that time. If you select yes, it will create " +"the file for you." +msgstr "" + +#: ../../tutorials/add-license-coc.md:59 +msgid "" +"You can add a `LICENSE` through the GitHub gui following the [ instructions " +"here](https://docs.github.com/en/communities/setting-up-your-project-for-" +"healthy-contributions/adding-a-license-to-a-repository)." +msgstr "" + +#: ../../tutorials/add-license-coc.md:60 +msgid "You can add the file manually as we are doing in this lesson." +msgstr "" + +#: ../../tutorials/add-license-coc.md:63 +msgid "If you completed the past lessons including" +msgstr "" + +#: ../../tutorials/add-license-coc.md:65 +msgid "[Making your code installable](installable-code.md) and" +msgstr "" + +#: ../../tutorials/add-license-coc.md:66 +msgid "[publishing your package to PyPI](publish-pypi.md)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:68 +msgid "" +"then you already have a `LICENSE` file containing text for the MIT " +"license in your Python package. Thus you can skip to the next section of " +"this tutorial which walks you through adding a `CODE_OF_CONDUCT`." +msgstr "" + +#: ../../tutorials/add-license-coc.md:70 +msgid "" +"If you don't yet have a `LICENSE` file in your directory, then continue " +"reading." +msgstr "" + +#: ../../tutorials/add-license-coc.md:73 +msgid "How to add a `LICENSE` to your package - the manual way" +msgstr "" + +#: ../../tutorials/add-license-coc.md:75 +msgid "" +"If you don't already have a `LICENSE` file, and you are not yet using a " +"platform such as GitHub or GitLab, then you can create a `LICENSE` file " +"by" +msgstr "" + +#: ../../tutorials/add-license-coc.md:77 +msgid "Create a new file called `LICENSE`. If you are using shell you can type:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:84 +msgid "Go to [choosealicense.com](https://choosealicense.com/)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:85 +msgid "Select permissive license" +msgstr "" + +#: ../../tutorials/add-license-coc.md:86 +msgid "" +"It will suggest that you use the [MIT " +"license](https://choosealicense.com/licenses/mit/)." +msgstr "" + +#: ../../tutorials/add-license-coc.md:87 +msgid "" +"Copy the license text that it provides into your `LICENSE` file that you " +"created above." +msgstr "" + +#: ../../tutorials/add-license-coc.md:88 +msgid "Save your file. You're all done!" +msgstr "" + +#: ../../tutorials/add-license-coc.md:90 +msgid "An overview of licenses in the scientific Python ecosystem" +msgstr "" + +#: ../../tutorials/add-license-coc.md:93 +msgid "" +"In the pyOpenSci [packaging guidebook](../documentation/repository-files" +"/license-files), we provide an overview of licenses in the scientific " +"Python ecosystem. We review why license files are important, which ones " +"are most commonly used for scientific software and how to select the " +"correct license." +msgstr "" + +#: ../../tutorials/add-license-coc.md:95 +msgid "" +"If you want a broad overview of why licenses are important for protecting" +" open source software, [check out this blog post that overviews the legal" +" side of things.](https://opensource.guide/legal/#just-give-me-the-tldr-" +"on-what-i-need-to-protect-my-project)" +msgstr "" + +#: ../../tutorials/add-license-coc.md +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:106 +msgid "" +"When you create a new GitHub repository you can add a `LICENSE` file " +"through the GitHub interface." +msgstr "" + +#: ../../tutorials/add-license-coc.md:111 +msgid "" +"Screenshot of the create new repository interface that GitHub provides. " +"The elements of this are the owner and repository name for the new repo. " +"Below that you can add a description of the repository. Below that you " +"can set it to be public or private. At the bottom of the interface there " +"is an Add a README checkbox where it will add a blank readme file for " +"you. At the very bottom there is a line to add a .gitignore file and " +"another to choose a license." +msgstr "" + +#: ../../tutorials/add-license-coc.md:113 +msgid "" +"Image showing the GitHub interface that allows you to add a `LICENSE` and" +" `README` file when you create a new repository." +msgstr "" + +#: ../../tutorials/add-license-coc.md +msgid "Add `LICENSE`: Existing GitHub repository" +msgstr "" + +#: ../../tutorials/add-license-coc.md:119 +msgid "" +"If you already have a GitHub repository for your package, then you can " +"add a `LICENSE` using the GitHub interface by adding a new file to the " +"repository." +msgstr "" + +#: ../../tutorials/add-license-coc.md:121 +msgid "" +"Follow the instructions to select and add a license to your repository on" +" the [GitHub LICENSE page](https://docs.github.com/en/communities" +"/setting-up-your-project-for-healthy-contributions/adding-a-license-" +"to-a-repository) ." +msgstr "" + +#: ../../tutorials/add-license-coc.md:122 +msgid "" +"Once you have added your `LICENSE` file, be sure to sync your git local " +"repository with the repository on GitHub.com. This means running `git " +"pull` to update your local branch." +msgstr "" + +#: ../../tutorials/add-license-coc.md:125 +msgid "" +"Image showing what the LICENSE file looks like in the GItHub interface. " +"At the top you can see the actual license which in this image is BSD " +"3-clause New or revised license. Then there is some text describing both " +"what the license is and the associated permissions for that specific " +"license. At the bottom of the image, the actual text for the license is " +"shown in the LICENSE file." +msgstr "" + +#: ../../tutorials/add-license-coc.md:127 +msgid "" +"You can view a summary of the `LICENSE` chosen on your project's GitHub " +"landing page." +msgstr "" + +#: ../../tutorials/add-license-coc.md:134 +msgid "" +"Now you know how to add a `LICENSE` to your project. Next, you'll learn " +"about the `CODE_OF_CONDUCT.md` file and how to add it to your package " +"directory." +msgstr "" + +#: ../../tutorials/add-license-coc.md:139 +msgid "What is a code of conduct file?" +msgstr "" + +#: ../../tutorials/add-license-coc.md:141 +msgid "" +"A `CODE_OF_CONDUCT` file is used to establish guidelines for how people " +"in your community interact." +msgstr "" + +#: ../../tutorials/add-license-coc.md:143 +msgid "" +"This file is critical to supporting your community as it grows. The " +"`CODE_OF_CONDUCT`:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:146 +msgid "" +"Establishes guidelines for how users and contributors interact with each " +"other and you in your software repository." +msgstr "" + +#: ../../tutorials/add-license-coc.md:147 +msgid "Identifies negative behaviors that you don't want in your interactions." +msgstr "" + +#: ../../tutorials/add-license-coc.md:149 +msgid "" +"You can use your code of conduct as a tool that can be referenced when " +"moderating challenging conversations." +msgstr "" + +#: ../../tutorials/add-license-coc.md:151 +msgid "What to put in your `CODE_OF_CONDUCT` file" +msgstr "" + +#: ../../tutorials/add-license-coc.md:153 +msgid "" +"If you are unsure of what language to add to your `CODE_OF_CONDUCT` file," +" we suggest that you adopt the [contributor covenant " +"language](https://www.contributor-" +"covenant.org/version/2/1/code_of_conduct/) as a starting place." +msgstr "" + +#: ../../tutorials/add-license-coc.md:156 +msgid "" +"![Contributor " +"Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:156 +msgid "Contributor Covenant" +msgstr "" + +#: ../../tutorials/add-license-coc.md:158 +msgid "" +"The `CODE_OF_CONDUCT.md` should be placed at the root of your project " +"directory, similar to the `LICENSE` file." +msgstr "" + +#: ../../tutorials/add-license-coc.md:160 +msgid "How to add a `CODE_OF_CONDUCT` file to your package directory" +msgstr "" + +#: ../../tutorials/add-license-coc.md:162 +msgid "" +"Add a `CODE_OF_CONDUCT.md` file to the root of your repository if it " +"doesn't already exist." +msgstr "" + +#: ../../tutorials/add-license-coc.md:168 +msgid "" +"Visit the [contributor covenant website](https://www.contributor-" +"covenant.org/) and add [the markdown version of their code of " +"conduct](https://www.contributor-" +"covenant.org/version/2/1/code_of_conduct/code_of_conduct.md) to your " +"`CODE_OF_CONDUCT.md` file. Be sure to fill in any placeholder " +"information. Read the text closely to ensure you both understand it and " +"also agree with its contents!" +msgstr "" + +#: ../../tutorials/add-license-coc.md:170 +msgid "That's it - you've now added a code of conduct to your package directory." +msgstr "" + +#: ../../tutorials/add-license-coc.md:172 +msgid "Additional Code of Conduct resources" +msgstr "" + +#: ../../tutorials/add-license-coc.md:175 +msgid "" +"[ Guide: `CODE_OF_CONDUCT.md` " +"files](https://docs.github.com/en/communities/setting-up-your-project-" +"for-healthy-contributions/adding-a-code-of-conduct-to-your-project)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:176 +msgid "" +"[pyOpenSci package guide `CODE_OF_CONDUCT.md` " +"overview](https://www.pyopensci.org/python-package-guide/documentation" +"/repository-files/code-of-conduct-file.html)" +msgstr "" + +#: ../../tutorials/add-license-coc.md:179 ../../tutorials/add-readme.md:233 +#: ../../tutorials/publish-conda-forge.md:463 +#: ../../tutorials/pyproject-toml.md:673 +msgid " Wrap up" +msgstr "" + +#: ../../tutorials/add-license-coc.md:181 +msgid "In this lesson and the [last lesson](add-readme), you have added a:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:183 +msgid "`README` file;" +msgstr "" + +#: ../../tutorials/add-license-coc.md:184 +msgid "`LICENSE` file and a" +msgstr "" + +#: ../../tutorials/add-license-coc.md:185 +msgid "`CODE_OF_CONDUCT` file." +msgstr "" + +#: ../../tutorials/add-license-coc.md:187 +msgid "" +"These are fundamental files needed for every scientific Python package " +"repository. These files help users understand how to use your package and" +" interact with package maintainers." +msgstr "" + +#: ../../tutorials/add-license-coc.md:191 +msgid "In the upcoming lessons, you will:" +msgstr "" + +#: ../../tutorials/add-license-coc.md:193 +msgid "" +"[Add more metadata to your `pyproject.toml` file](pyproject-toml) to " +"support building and publishing your package on PyPI." +msgstr "" + +#: ../../tutorials/add-license-coc.md:194 +msgid "" +"Publish a new version of your Python package to the test PyPI to preview " +"the updated metadata landing page." +msgstr "" + +#: ../../tutorials/add-license-coc.md:199 +#: ../../tutorials/installable-code.md:642 +#: ../../tutorials/publish-conda-forge.md:475 +#: ../../tutorials/publish-pypi.md:394 +msgid "Footnotes" +msgstr "" + +#: ../../tutorials/add-license-coc.md:201 +msgid "https://opensource.org/license/mit/" +msgstr "" + +#: ../../tutorials/add-license-coc.md:202 +msgid "https://opensource.org/license/bsd-3-clause/" +msgstr "" + +#: ../../tutorials/add-readme.md:1 +msgid "Add a README file to your Python package" +msgstr "" + +#: ../../tutorials/add-readme.md:3 +msgid "In the previous lessons you learned:" +msgstr "" + +#: ../../tutorials/add-readme.md:5 +msgid "[What a Python package is](intro.md)" +msgstr "" + +#: ../../tutorials/add-readme.md:6 +msgid "[How to make your code installable](installable-code)" +msgstr "" + +#: ../../tutorials/add-readme.md:7 +msgid "[How to publish your package to (test) PyPI](publish-pypi.md)" +msgstr "" + +#: ../../tutorials/add-readme.md:8 +msgid "[How to publish your package to conda-forge](publish-conda-forge.md)" +msgstr "" + +#: ../../tutorials/add-readme.md:14 +msgid "How to add a **README.md** file to your package." +msgstr "" + +#: ../../tutorials/add-readme.md:15 +msgid "What the core elements of a **README.md** file are." +msgstr "" + +#: ../../tutorials/add-readme.md:18 +msgid "What is a README file?" +msgstr "" + +#: ../../tutorials/add-readme.md:20 +msgid "" +"The `README.md` file is a markdown file located at the root of your " +"project directory that helps a user understand:" +msgstr "" + +#: ../../tutorials/add-readme.md:23 +msgid "You package's name" +msgstr "" + +#: ../../tutorials/add-readme.md:24 +msgid "" +"What the package does. Your README file should clearly state the " +"problem(s) that your software is designed to solve and its target " +"audience." +msgstr "" + +#: ../../tutorials/add-readme.md:25 +msgid "The current development \"state\" of the package (through badges)" +msgstr "" + +#: ../../tutorials/add-readme.md:26 +msgid "How to get started with using your package." +msgstr "" + +#: ../../tutorials/add-readme.md:27 +msgid "How to contribute to your package" +msgstr "" + +#: ../../tutorials/add-readme.md:28 +msgid "How to cite your package" +msgstr "" + +#: ../../tutorials/add-readme.md:30 +msgid "" +"Your **README.md** file is important as it is often the first thing that " +"someone sees before they install your package. The README file is also " +"used to populate your PyPI landing page." +msgstr "" + +#: ../../tutorials/add-readme.md:32 +msgid "" +"Note that there is no specific content structure for README files. " +"However, this tutorial outlines the sections that we suggest that you " +"include in your README file." +msgstr "" + +#: ../../tutorials/add-readme.md:36 +msgid "Create a README.md file for your package" +msgstr "" + +#: ../../tutorials/add-readme.md:38 +msgid "It's time to add a `README.md` file to your project directory." +msgstr "" + +#: ../../tutorials/add-readme.md:40 +msgid "Step 0: Create a README file" +msgstr "" + +#: ../../tutorials/add-readme.md:41 +msgid "" +"To get started, if you don't already have a README.md file in your " +"project directory, create one." +msgstr "" + +#: ../../tutorials/add-readme.md:44 +msgid "If you created your project directory from" +msgstr "" + +#: ../../tutorials/add-readme.md:46 +msgid "a GitHub repository online" +msgstr "" + +#: ../../tutorials/add-readme.md:47 +msgid "using `hatch init`" +msgstr "" + +#: ../../tutorials/add-readme.md:49 +msgid "Then you may already have a README.MD file in your project directory." +msgstr "" + +#: ../../tutorials/add-readme.md:55 +msgid "Step 1: Add the name of your package as the README title" +msgstr "" + +#: ../../tutorials/add-readme.md:57 +msgid "At the top of the `README.md` file, add the name of your package." +msgstr "" + +#: ../../tutorials/add-readme.md:59 +msgid "" +"If you are using markdown it should be a header 1 (H1) tag which is " +"denoted with a single `#` sign." +msgstr "" + +#: ../../tutorials/add-readme.md:61 +msgid "`# Package-title-here`" +msgstr "" + +#: ../../tutorials/add-readme.md:63 +msgid "Step 2: add badges to the top of your README file" +msgstr "" + +#: ../../tutorials/add-readme.md:65 +msgid "" +"It's common for maintainers to add badges to the top of their README " +"files. Badges allow you and your package users to track things like:" +msgstr "" + +#: ../../tutorials/add-readme.md:67 +msgid "Broken documentation and test builds." +msgstr "" + +#: ../../tutorials/add-readme.md:68 +msgid "Versions of your package that are on PyPI and conda." +msgstr "" + +#: ../../tutorials/add-readme.md:69 +msgid "" +"Whether your package has been reviewed and vetted by an organization such" +" as pyOpenSci and/or JOSS." +msgstr "" + +#: ../../tutorials/add-readme.md:71 +msgid "" +"If you have already published your package to pypi.org you can use " +"[shields.io to create a package version badge](https://shields.io/badges" +"/py-pi-version). This badge will dynamically update as you release new " +"versions of your package to PyPI." +msgstr "" + +#: ../../tutorials/add-readme.md:73 +msgid "" +"If not, you can leave the top empty for now and add badges to your README" +" at a later point as they make sense." +msgstr "" + +#: ../../tutorials/add-readme.md:75 +msgid "Step 3: Add a description of what your package does" +msgstr "" + +#: ../../tutorials/add-readme.md:77 +msgid "" +"Below the badges (if you have them), add a section of text that provides " +"an easy-to-understand overview of what your package does." +msgstr "" + +#: ../../tutorials/add-readme.md:81 +msgid "Keep this section short." +msgstr "" + +#: ../../tutorials/add-readme.md:82 +msgid "Try to avoid jargon." +msgstr "" + +#: ../../tutorials/add-readme.md:83 +msgid "" +"Define technical terms that you use to make the description accessible to" +" more people." +msgstr "" + +#: ../../tutorials/add-readme.md:85 +msgid "" +"Remember that the more people understand what your package does, the more" +" people will use it." +msgstr "" + +#: ../../tutorials/add-readme.md:87 +msgid "Step 4: Add package installation instructions" +msgstr "" + +#: ../../tutorials/add-readme.md:89 +msgid "Next, add instructions that tell users how to install your package." +msgstr "" + +#: ../../tutorials/add-readme.md:91 +msgid "" +"For example, can they use pip to install your package? `python -m pip " +"install packagename`" +msgstr "" + +#: ../../tutorials/add-readme.md:94 +msgid "or conda?" +msgstr "" + +#: ../../tutorials/add-readme.md:96 +msgid "`conda install -c conda-forge packagename`." +msgstr "" + +#: ../../tutorials/add-readme.md:98 +msgid "" +"If you haven't yet published your package to pypi.org then you can skip " +"this section and come back and add these instructions later." +msgstr "" + +#: ../../tutorials/add-readme.md:102 +msgid "Step 5: Any additional setup" +msgstr "" + +#: ../../tutorials/add-readme.md:104 +msgid "" +"In some cases, your package users may need to manually install other " +"tools in order to use your package. If that is the case, be sure to add a" +" section on additional setup to your README file." +msgstr "" + +#: ../../tutorials/add-readme.md:109 +msgid "" +"Here, briefly document (or link to documentation for) any additional " +"setup that is required to use your package. This might include:" +msgstr "" + +#: ../../tutorials/add-readme.md:113 +msgid "authentication information, if it is applicable to your package." +msgstr "" + +#: ../../tutorials/add-readme.md:114 +msgid "additional tool installations, such as GDAL." +msgstr "" + +#: ../../tutorials/add-readme.md:117 +msgid "" +"Many packages won't need an additional setup section in their README. In " +"that case you can always skip this section." +msgstr "" + +#: ../../tutorials/add-readme.md:122 +msgid "Step 6: Add a get started section" +msgstr "" + +#: ../../tutorials/add-readme.md:124 +msgid "" +"Next add a get-started section. Within this section, add a small code " +"example that demonstrates importing and using some of the functionality " +"in your package." +msgstr "" + +#: ../../tutorials/add-readme.md:127 +msgid "Provide a fully functional code snippet if possible" +msgstr "" + +#: ../../tutorials/add-readme.md:130 +msgid "" +"It is important to try to make the code examples that you provide your " +"users as useful as possible." +msgstr "" + +#: ../../tutorials/add-readme.md:132 +msgid "" +"Be sure to provide a copy/paste code example that will work as-is when " +"pasted into a Jupyter Notebook or .py file if that is possible." +msgstr "" + +#: ../../tutorials/add-readme.md:134 +msgid "" +"If there are tokens and other steps needed to run your package, be sure " +"to be clear about what those steps are." +msgstr "" + +#: ../../tutorials/add-readme.md:137 +msgid "For the pyosPackage, a short get started demo might look like this:" +msgstr "" + +#: ../../tutorials/add-readme.md:145 +msgid "" +"Or it could simply be a link to a getting started tutorial that you have " +"created. If you don't have this yet, you can leave it empty for the time " +"being." +msgstr "" + +#: ../../tutorials/add-readme.md:148 +msgid "" +"This would also be a great place to add links to tutorials that help " +"users understand how to use your package for common workflows." +msgstr "" + +#: ../../tutorials/add-readme.md:153 +msgid "Step 7: Community section" +msgstr "" + +#: ../../tutorials/add-readme.md:155 +msgid "" +"The community section of your README file is a place to include " +"information for users who may want to engage with your project. This " +"engagement will likely happen on a platform like GitHub or GitLab." +msgstr "" + +#: ../../tutorials/add-readme.md:157 +msgid "" +"In the community section, you will add links to your contributing guide " +"and `CODE_OF_CONDUCT.md`. You will create a [`CODE_OF_CONDUCT.md` file in" +" the next lesson](add-license-coc)." +msgstr "" + +#: ../../tutorials/add-readme.md:160 +msgid "" +"As your package grows you may also have a link to a development guide " +"that contributors and your maintainer team will follow. The development " +"guide outlines how to perform maintenance tasks such as:" +msgstr "" + +#: ../../tutorials/add-readme.md:163 +msgid "running tests" +msgstr "" + +#: ../../tutorials/add-readme.md:164 +msgid "making package releases" +msgstr "" + +#: ../../tutorials/add-readme.md:165 +msgid "building documentation" +msgstr "" + +#: ../../tutorials/add-readme.md:166 +msgid "and more." +msgstr "" + +#: ../../tutorials/add-readme.md:170 +msgid "Step 8: Citation information" +msgstr "" + +#: ../../tutorials/add-readme.md:172 +msgid "" +"Finally it is important to let users know how to cite your package. You " +"can communicate citation information in a few different ways." +msgstr "" + +#: ../../tutorials/add-readme.md:175 +msgid "" +"You can use a tool such as zenodo to create a DOI and associated citation" +" information for your package if it is hosted on a platform such as " +"GitHub. [Check out this short tutorial that covers setting that " +"up.](https://coderefinery.github.io/github-without-command-line/doi/)" +msgstr "" + +#: ../../tutorials/add-readme.md:179 +msgid "" +"Alternatively if you send your package through a peer review process such" +" as the [one lead by pyOpenSci](https://www.pyopensci.org/about-peer-" +"review/index.html). After being accepted by pyOpenSci, if your package is" +" in scope, you can be accepted by the Journal of Open Source Software and" +" get a cross-ref DOI through [our partnership with the Journal of Open " +"Source Software.](https://www.pyopensci.org/about-peer-review/index.html)" +msgstr "" + +#: ../../tutorials/add-readme.md:183 +msgid "The finished README file" +msgstr "" + +#: ../../tutorials/add-readme.md:185 +msgid "Your finished `README.md` file should look something like this:" +msgstr "" + +#: ../../tutorials/add-readme.md:235 +msgid "" +"It's important to consider the information that a new user or contributor" +" might need when creating your `README.md` file. While there is no " +"perfect template, above is a set of recommendations as you are just " +"getting started. You may find the need for other elements to be added to " +"this file as you further develop your package and as a community begins " +"to use your package." +msgstr "" + +#: ../../tutorials/add-readme.md:241 +msgid "" +"In the [next lesson](add-license-coc.md), you will add a LICENSE file to " +"your Python package. A license file is critical as it tells users how " +"they legally can (and can't) use your package. It also:" +msgstr "" + +#: ../../tutorials/add-readme.md:245 +msgid "Builds trust with your users" +msgstr "" + +#: ../../tutorials/add-readme.md:246 +msgid "Discourages misuse of your package and associated code" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:1 ../../tutorials/intro.md:27 +#: ../../tutorials/setup-py-to-pyproject-toml.md:24 +msgid "Get to know Hatch" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:3 +msgid "" +"Our Python packaging tutorials use the tool Hatch. 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:6 +msgid "Install Hatch" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:7 +msgid "" +"To begin, install Hatch from the command line using " +"[pipx](https://pipx.pypa.io/stable/)" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:14 +msgid "" +"Hatch can also be installed directly using `pip` or `conda`, but we " +"encourage you to use `pipx`. This is because `pipx` will ensure that your" +" package is available across all of your Python environments on your " +"computer rather than just in the environment that you install it into. If" +" you install hatch this way you will have to take care that the " +"environment it is installed into is activated for the command to work." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:21 +msgid "" +"You can check that hatch is working properly by issuing a simple command " +"to get the version" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:28 +msgid "Note the version numbers will likely be different" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:30 +msgid "Configure hatch" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:32 +msgid "" +"Once you have installed Hatch, you will want to customize the " +"configuration." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:34 +msgid "" +"Hatch stores your configuration information in a [`config.toml` " +"file](https://hatch.pypa.io/latest/config/project-templates/)." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:36 +msgid "" +"While you can update the `config.toml` file through the command line, it " +"might be easier to look at it and update it in a text editor if you are " +"using it for the first time." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:39 +msgid "Step 1: Open and edit your `config.toml` file" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:41 +msgid "" +"To open the config file in your file browser, run the following command " +"in your shell:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:43 +msgid "`hatch config explore`" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:45 +msgid "" +"This will open up a directory window that will allow you to double click " +"on the file and open it in your favorite text editor." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:47 +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:54 +msgid "Step 2 - update your email and name" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:56 +msgid "" +"Once the file is open, update the [template] table of the `config.toml` " +"file with your name and email. This information will be used in any " +"`pyproject.toml` metadata files that you create using Hatch." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:64 +msgid "Step 3" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:66 +msgid "Next, set tests to false in the `[template.plugins.default]` table." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:68 +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:73 +msgid "Your `config.toml` file should look something like the one below." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:111 +msgid "" +"Also notice that the default license option is MIT. While we will discuss" +" license in more detail in a later lesson, the MIT license is the " +"recommended permissive license from " +"[choosealicense.com](https://www.choosealicense.com) and as such we will " +"use it for this tutorial series." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:116 +msgid "You are of course welcome to select another license." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:118 +#: ../../tutorials/installable-code.md:22 +#: ../../tutorials/installable-code.md:411 +#: ../../tutorials/installable-code.md:502 ../../tutorials/intro.md:226 +#: ../../tutorials/publish-pypi.md:3 ../../tutorials/publish-pypi.md:178 +#: ../../tutorials/publish-pypi.md:350 ../../tutorials/pyproject-toml.md:718 +msgid "Todo" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:119 +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:122 +msgid "Step 4: Close the config file and run `hatch config show`" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:124 +msgid "" +"Once you have completed the steps above run the following command in your" +" shell." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:126 +msgid "`hatch config show`" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:128 +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:130 +msgid "Hatch features" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:132 +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:135 +msgid "Comparison to other tools" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:137 +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:140 +msgid "[More on Hatch here](hatch)" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:142 +msgid "A few features that Hatch offers" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:145 +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:147 +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:149 +msgid "Use `hatch -h` to see all of the available commands." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:152 +msgid "What's next" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:154 +msgid "" +"In the next lesson you'll learn how to package and make your code " +"installable using Hatch." +msgstr "" + +#: ../../tutorials/installable-code.md:6 +msgid "Make your Python code installable" +msgstr "" + +#: ../../tutorials/installable-code.md:8 +msgid "What we previously covered" +msgstr "" + +#: ../../tutorials/installable-code.md:9 +msgid "" +"[In the previous lesson](intro), you learned about what a Python package " +"is. You also learned about the [benefits of creating a Python package" +"](package-benefits)." +msgstr "" + +#: ../../tutorials/installable-code.md:13 +msgid "" +"Your next step in our packaging tutorial series is to create a Python " +"package that is installable both locally and remotely from a website such" +" as GitHub (or GitLab). The package that you create in this lesson will " +"have the bare minimum elements needed to be installable into a Python " +"environment." +msgstr "" + +#: ../../tutorials/installable-code.md:18 +msgid "" +"Making your code installable is an important steps towards creating a " +"full Python package that is directly installable from PyPI." +msgstr "" + +#: ../../tutorials/installable-code.md:23 +msgid "" +"Is it clear where to add commands? Bash vs. Python console Bash vs. Zsh " +"is different" +msgstr "" + +#: ../../tutorials/installable-code.md:25 +msgid "Does this lesson run as expected on windows and mac?" +msgstr "" + +#: ../../tutorials/installable-code.md:26 +msgid "" +"ADD: note about what makes something \"package worthy\", with a common " +"misconception being that a package should be production-ready code that's" +" valuable to a broad audience. this may not be a pervasive misconception " +"in Python, but a quick break-out with an explanation of what a package " +"can consist of would be helpful." +msgstr "" + +#: ../../tutorials/installable-code.md:31 +msgid "" +"Diagram showing the basic steps to creating an installable package. There" +" are 4 boxes with arrows pointing towards the right. The boxes read, your" +" code, create package structure, add metadata to pyproject.toml and pip " +"install package." +msgstr "" + +#: ../../tutorials/installable-code.md:33 +msgid "" +"A basic installable package needs a few things: code, a [specific package" +" file structure](https://www.pyopensci.org/python-package-guide/package-" +"structure-code/python-package-structure.html) and a `pyproject.toml` " +"containing your package's name and version. Once you have these items in " +"the correct directory structure, you can pip install your package into " +"any environment on your computer. You will learn how to create a basic " +"installable package in this lesson." +msgstr "" + +#: ../../tutorials/installable-code.md:37 +msgid "About this lesson" +msgstr "" + +#: ../../tutorials/installable-code.md:43 +msgid "" +"How to make your code installable into any Python environment both " +"locally and from GitHub" +msgstr "" + +#: ../../tutorials/installable-code.md:44 +msgid "" +"How to create a basic `pyproject.toml` file that includes package " +"dependencies and metadata. This file is required to make your package " +"installable." +msgstr "" + +#: ../../tutorials/installable-code.md:45 +msgid "" +"How to declare a [build backend](build_backends) which will be used to " +"[build](build-package) and install your package" +msgstr "" + +#: ../../tutorials/installable-code.md:46 +msgid "How to install your package in editable mode for interactive development" +msgstr "" + +#: ../../tutorials/installable-code.md:48 +msgid "**What you need to complete this lesson**" +msgstr "" + +#: ../../tutorials/installable-code.md:50 +msgid "" +"To complete this lesson you will need a local Python environment and " +"shell on your computer. You will also need to have [Hatch installed](get-" +"to-know-hatch)." +msgstr "" + +#: ../../tutorials/installable-code.md:53 +msgid "" +"If you are using Windows or are not familiar with Shell, you may want to " +"check out the Carpentries shell lesson[^shell-lesson]. Windows users will" +" likely need to configure a tool for any Shell and git related steps." +msgstr "" + +#: ../../tutorials/installable-code.md:55 +msgid "**What comes next**" +msgstr "" + +#: ../../tutorials/installable-code.md:57 +msgid "In the upcoming lessons you will learn how to:" +msgstr "" + +#: ../../tutorials/installable-code.md:59 +msgid "[Publish your package to PyPI](publish-pypi)" +msgstr "" + +#: ../../tutorials/installable-code.md:60 +msgid "Add a README file to your package to support community use" +msgstr "" + +#: ../../tutorials/installable-code.md:61 +msgid "" +"Add additional project metadata to your package to support PyPI " +"publication" +msgstr "" + +#: ../../tutorials/installable-code.md:67 +msgid "" +"This diagram has two smaller boxes with arrows pointing to the right to a" +" Python environment. The small boxes read your-package and pip install " +"package. The environment box on the right reads - your Python " +"environment. It them lists your-package along with a few other core " +"packages such as Matplotlib, NumPy, Pandas, Xarray and GeoPandas." +msgstr "" + +#: ../../tutorials/installable-code.md:69 +msgid "" +"Making your code installable is the first step towards creating a " +"publishable Python package. Once your code is installable, it is a Python" +" package and can be added to any Python environment on your computer and " +"imported in the same way that you might import a package such as Pandas " +"or GeoPandas. If your code is on GitHub or GitLab you can also install it" +" directly from there." +msgstr "" + +#: ../../tutorials/installable-code.md:74 +msgid "About the Python package directory structure" +msgstr "" + +#: ../../tutorials/installable-code.md:76 +msgid "" +"To make your Python code installable you need to create a specific " +"directory structure with the following elements:" +msgstr "" + +#: ../../tutorials/installable-code.md:78 +msgid "A `pyproject.toml` file." +msgstr "" + +#: ../../tutorials/installable-code.md:79 +msgid "A specific directory structure." +msgstr "" + +#: ../../tutorials/installable-code.md:80 +msgid "Some code." +msgstr "" + +#: ../../tutorials/installable-code.md:81 +msgid "An `__init__.py` file in your code directory." +msgstr "" + +#: ../../tutorials/installable-code.md:83 +msgid "The directory structure you’ll create in this lesson will look like this:" +msgstr "" + +#: ../../tutorials/installable-code.md:95 +msgid "About the basic package directory structure" +msgstr "" + +#: ../../tutorials/installable-code.md:97 +msgid "Notice a few things about the above layout:" +msgstr "" + +#: ../../tutorials/installable-code.md:99 +msgid "" +"Your package code lives within a `src/packagename` directory. We suggest " +"that you use `src` (short for **source code**) directory as it [ensures " +"that you are running tests on the installed version of your " +"code](https://www.pyopensci.org/python-package-guide/package-structure-" +"code/python-package-structure.html#the-src-layout-and-testing)." +msgstr "" + +#: ../../tutorials/installable-code.md:100 +msgid "" +"Within the `src` directory you have a package directory called " +"`pyospackage`. Use the name of your package for that directory name. This" +" will be the name for importing your package in Python code once " +"installed." +msgstr "" + +#: ../../tutorials/installable-code.md:101 +msgid "" +"In your package directory, you have an `__init__.py` file and all of your" +" Python modules. You will learn more about the `__init__.py` file below." +msgstr "" + +#: ../../tutorials/installable-code.md:102 +msgid "The `pyproject.toml` file lives at the root directory of your package." +msgstr "" + +#: ../../tutorials/installable-code.md:103 +msgid "" +"The name of the root directory for the package is **pyospackage** which " +"is the name of the package. This is not a requirement but you will often " +"see that the GitHub / GitLab repository and the root directory name are " +"the same as the package name." +msgstr "" + +#: ../../tutorials/installable-code.md:105 +msgid "What is an `__init__.py` file?" +msgstr "" + +#: ../../tutorials/installable-code.md:107 +msgid "" +"The `__init__.py` file tells Python that a directory should be treated as" +" a Python package. As such, a directory with an `__init__.py` file can be" +" imported directly into Python. The `__init__.py` file does not need to " +"contain any code in order for Python to recognize it; it can be empty." +msgstr "" + +#: ../../tutorials/installable-code.md:111 +msgid "" +"For example, following the file structure example above which has an " +"`__init__.py` file within it, you can run:" +msgstr "" + +#: ../../tutorials/installable-code.md:117 ../../tutorials/pyproject-toml.md:48 +msgid "What is a pyproject.toml file?" +msgstr "" + +#: ../../tutorials/installable-code.md:119 +msgid "The **pyproject.toml** file is:" +msgstr "" + +#: ../../tutorials/installable-code.md:121 +msgid "" +"Where you define your project’s metadata (including its name, authors, " +"license, etc)" +msgstr "" + +#: ../../tutorials/installable-code.md:122 +msgid "Where you define dependencies (the packages that it depends on)" +msgstr "" + +#: ../../tutorials/installable-code.md:123 +msgid "" +"Used to specify and configure what build backend you want to use to " +"[build your package](../package-structure-code/python-package-" +"distribution-files-sdist-wheel)." +msgstr "" + +#: ../../tutorials/installable-code.md:125 +msgid "" +"After the `__init__.py` and `pyproject.toml` files have been added, your " +"package can be built and distributed as an installable Python package " +"using tools such as pip. Note that the `pyproject.toml` file needs to " +"have a few basic items defined for the package to be installable " +"including:" +msgstr "" + +#: ../../tutorials/installable-code.md:131 +msgid "The `build-backend` that you want to use," +msgstr "" + +#: ../../tutorials/installable-code.md:132 +msgid "The project `name` and `version`." +msgstr "" + +#: ../../tutorials/installable-code.md:134 +msgid "Why the pyproject.toml file is important" +msgstr "" + +#: ../../tutorials/installable-code.md:138 +msgid "" +"The `pyproject.toml` file replaces some of the functionality of both the " +"`setup.py` file and `setup.cfg` files. If you try to pip install a " +"package with no `pyproject.toml` you will get the following error:" +msgstr "" + +#: ../../tutorials/installable-code.md:150 +msgid "Note about `setup.py`" +msgstr "" + +#: ../../tutorials/installable-code.md:154 +msgid "" +"If your project already defines a `setup.py` file, Hatch can be used to " +"automatically create the `pyproject.toml`." +msgstr "" + +#: ../../tutorials/installable-code.md:155 +msgid "" +"See [Using Hatch to Migrate setup.py to a pyproject.toml ](setup-py-to-" +"pyproject-toml.md)" +msgstr "" + +#: ../../tutorials/installable-code.md:161 +msgid "Time to create your Python package!" +msgstr "" + +#: ../../tutorials/installable-code.md:163 +msgid "" +"Now that you understand the basics of the Python package directory " +"structure, and associated key files (`__init__.py` and `pyproject.toml`)," +" it's time to create your Python package! Below you will create a " +"directory structure similar to the structure described above using Hatch." +msgstr "" + +#: ../../tutorials/installable-code.md:167 +msgid "Step 1: Set Up the Package Directory Structure" +msgstr "" + +#: ../../tutorials/installable-code.md:169 +msgid "Open your shell or preferred terminal." +msgstr "" + +#: ../../tutorials/installable-code.md:170 +msgid "" +"Use the shell `cd` command to navigate in your shell to the location " +"where you'd like your package directory to live. Hatch will create the " +"package directory for you" +msgstr "" + +#: ../../tutorials/installable-code.md:171 +msgid "Choose a name for your package. The name should:" +msgstr "" + +#: ../../tutorials/installable-code.md:172 +msgid "Have no spaces (*Required*)" +msgstr "" + +#: ../../tutorials/installable-code.md:173 +msgid "" +"Use all lowercase characters (*Recommended*). For this tutorial we will " +"use `pyospackage`." +msgstr "" + +#: ../../tutorials/installable-code.md:174 +msgid "" +"Only use letter and the characters _ or - in the name. This means that " +"the name `pyos*package` is not an acceptable name. However, the names " +"`pyos_package` or `pyos-package` both are ok" +msgstr "" + +#: ../../tutorials/installable-code.md:176 +msgid "Hatch and project names" +msgstr "" + +#: ../../tutorials/installable-code.md:177 +msgid "" +"Hatch makes some decisions for your project's name when you run `hatch " +"new`" +msgstr "" + +#: ../../tutorials/installable-code.md:179 +msgid "These include using:" +msgstr "" + +#: ../../tutorials/installable-code.md:180 +msgid "dashes for the top level directory" +msgstr "" + +#: ../../tutorials/installable-code.md:181 +msgid "dashes for the project name in the pyproject.toml" +msgstr "" + +#: ../../tutorials/installable-code.md:182 +msgid "underscores for the package directory name" +msgstr "" + +#: ../../tutorials/installable-code.md:196 +msgid "If you use a name with underscores, Hatch will return the same thing:" +msgstr "" + +#: ../../tutorials/installable-code.md:209 +msgid "" +"In both of the examples above the project name in the pyproject.toml file" +" that hatch creates is `pyos-package`." +msgstr "" + +#: ../../tutorials/installable-code.md:213 +msgid "Next run:" +msgstr "" + +#: ../../tutorials/installable-code.md:228 +msgid "Your final project directory structure should look like this:" +msgstr "" + +#: ../../tutorials/installable-code.md:243 +msgid "Step 2: Add module to your package" +msgstr "" + +#: ../../tutorials/installable-code.md:245 +msgid "" +"A Python module refers to a `.py` file containing the code that you want " +"your package to access and run. Within the `pyospackage` subdirectory, " +"add at least one Python modules (.py files)." +msgstr "" + +#: ../../tutorials/installable-code.md:247 +msgid "" +"If you don't have code already and are just learning how to create a " +"Python package, then create an empty `add_numbers.py` file. You will " +"populate the `add_numbers.py` file with code provided below." +msgstr "" + +#: ../../tutorials/installable-code.md:250 +msgid "Python modules and the `__init__.py` file" +msgstr "" + +#: ../../tutorials/installable-code.md:254 +msgid "" +"When you see the word module, we are referring to a `.py` file containing" +" Python code." +msgstr "" + +#: ../../tutorials/installable-code.md:257 +msgid "" +"The `__init__.py` allows Python to recognize that a directory contains " +"at least one module that may be imported and used in your code. A package" +" can have multiple modules[^python-modules]." +msgstr "" + +#: ../../tutorials/installable-code.md:261 +msgid "Your project directory should now look like this:" +msgstr "" + +#: ../../tutorials/installable-code.md:271 +msgid "Step 3: Add code to your module" +msgstr "" + +#: ../../tutorials/installable-code.md:273 +msgid "" +"If you are following along and making a Python package from scratch then " +"you can add the code below to your `add_numbers.py` module. The function " +"below adds two integers together and returns the result. Notice that the " +"code below has a few features that we will review in future tutorials:" +msgstr "" + +#: ../../tutorials/installable-code.md:275 +msgid "It has a [numpy-style docstring](numpy-docstring)" +msgstr "" + +#: ../../tutorials/installable-code.md:276 +msgid "It uses [typing](type-hints)" +msgstr "" + +#: ../../tutorials/installable-code.md:278 +msgid "" +"Python can support many different docstrings formats depending on the " +"documentation build system you wish to use. The most popular supported " +"formats for documenting Python objects are NumPy Style " +"Docstring[^numpydoc], Google Style Docstring[^googledoc], and the Epytext" +" Style Docstrings[^epytextdoc]." +msgstr "" + +#: ../../tutorials/installable-code.md:280 +msgid "**pyOpenSci recommends using the NumPy Docstring convention.**" +msgstr "" + +#: ../../tutorials/installable-code.md:282 +msgid "" +"If you aren’t familiar with docstrings or typing yet, that is ok. You can" +" review [this page in the pyOpenSci packaging " +"guide](https://www.pyopensci.org/python-package-guide/documentation" +"/write-user-documentation/document-your-code-api-docstrings.html) for an " +"overview of both topics." +msgstr "" + +#: ../../tutorials/installable-code.md:311 +msgid "Step 4: Modify metadata in your `pyproject.toml` file" +msgstr "" + +#: ../../tutorials/installable-code.md:313 +msgid "" +"Next, you will modify some of the metadata (information) that Hatch adds " +"to your `pyproject.toml` file. You are are welcome to copy the file we " +"have in our [example pyospackage GitHub " +"repository](https://github.com/pyOpenSci/pyosPackage)." +msgstr "" + +#: ../../tutorials/installable-code.md:317 +msgid "Brief overview of the TOML file" +msgstr "" + +#: ../../tutorials/installable-code.md:320 +msgid "" +"[The TOML format](https://toml.io/en/) consists of tables and variables. " +"Tables are sections of information denoted by square brackets:" +msgstr "" + +#: ../../tutorials/installable-code.md:322 +msgid "`[this-is-a-table]`." +msgstr "" + +#: ../../tutorials/installable-code.md:324 +msgid "" +"Tables can contain variables within them defined by an variable name and " +"an `=` sign. For instance, a `build-system` table most often holds two " +"(2) variables:" +msgstr "" + +#: ../../tutorials/installable-code.md:327 +msgid "" +"`requires = `, which tells a build tool what tools it needs to install " +"prior to building your package. In this case " +"[hatchling](https://pypi.org/project/hatchling/)" +msgstr "" + +#: ../../tutorials/installable-code.md:329 +msgid "" +"`build-backend = `, which is used to define the specific build-backend " +"name, (in this example we are using `hatchling.build`)." +msgstr "" + +#: ../../tutorials/installable-code.md:338 +msgid "" +"TOML organizes data structures, defining relationships within a " +"configuration file." +msgstr "" + +#: ../../tutorials/installable-code.md:341 +msgid "" +"[Learn more about the pyproject.toml format here.](../package-structure-" +"code/pyproject-toml-python-package-metadata)" +msgstr "" + +#: ../../tutorials/installable-code.md:345 +msgid "" +"You will learn more about the `pyproject.toml` format in the [next lesson" +" when you add additional metadata / information to this file.](pyproject-" +"toml.md)" +msgstr "" + +#: ../../tutorials/installable-code.md:348 +msgid "" +"Open up the `pyproject.toml` file that Hatch created in your favorite " +"text editor. It should look something like the example below." +msgstr "" + +#: ../../tutorials/installable-code.md:390 +msgid "Edit the file as follows:" +msgstr "" + +#: ../../tutorials/installable-code.md:392 +msgid "" +"Delete `dynamic = [\"version\"]`: This sets up dynamic versioning based " +"on tags stored in your git commit history. We will walk through " +"implementing this in a later lesson." +msgstr "" + +#: ../../tutorials/installable-code.md:393 +msgid "" +"Add `version = \"0.1\"` in the place of `dynamic = [\"version\"]` which " +"you just deleted. This sets up manual versioning." +msgstr "" + +#: ../../tutorials/installable-code.md:394 +msgid "Fill in the description if it doesn't already exist." +msgstr "" + +#: ../../tutorials/installable-code.md:404 +msgid "Remove the `[tool.hatch.version]` table from the bottom of the file." +msgstr "" + +#: ../../tutorials/installable-code.md:412 +msgid "" +"When this lesson exists, uncomment this admonition You will learn how to " +"automate defining a package version using git tags in the version and " +"release your package lesson." +msgstr "" + +#: ../../tutorials/installable-code.md:417 +msgid "OPTIONAL: Adjust project classifiers" +msgstr "" + +#: ../../tutorials/installable-code.md:419 +msgid "" +"Hatch by default provides a list of classifiers that define what Python " +"versions your package supports. These classifiers do not in any way " +"impact your package's build and are primarily intended to be used when " +"you publish your package to PyPI." +msgstr "" + +#: ../../tutorials/installable-code.md:424 +msgid "" +"If you don't plan on publishing to PyPI, you can skip this section. " +"However, if you wish, you can clean it up a bit." +msgstr "" + +#: ../../tutorials/installable-code.md:427 +msgid "To begin:" +msgstr "" + +#: ../../tutorials/installable-code.md:429 +msgid "Remove support for Python 3.8" +msgstr "" + +#: ../../tutorials/installable-code.md:430 +msgid "" +"Within the `[project]` table, update `requires-python = \">3.8\"` to " +"`requires-python = \">3.9\"`" +msgstr "" + +#: ../../tutorials/installable-code.md:432 +msgid "" +"Since you are creating a pure Python package in this lesson, you can " +"remove the following classifiers:" +msgstr "" + +#: ../../tutorials/installable-code.md:442 +msgid "Your new pyproject.toml file should now look something like this:" +msgstr "" + +#: ../../tutorials/installable-code.md:477 +msgid "The bare minimum needed in a pyproject.toml file" +msgstr "" + +#: ../../tutorials/installable-code.md:480 +msgid "" +"The core information that you need in a `pyproject.toml` file in order to" +" publish on PyPI is your **package's name** and the **version**. " +"However, we suggest that you flesh out your metadata early on in the " +"`pyproject.toml` file." +msgstr "" + +#: ../../tutorials/installable-code.md:482 +msgid "" +"Once you have your project metadata in the pyproject.toml file, you will " +"rarely update it. In the next lesson you’ll add more metadata and " +"structure to this file." +msgstr "" + +#: ../../tutorials/installable-code.md:486 +msgid "Step 5: Install your package locally" +msgstr "" + +#: ../../tutorials/installable-code.md:488 +msgid "At this point you should have:" +msgstr "" + +#: ../../tutorials/installable-code.md:490 +msgid "A project directory structure with a `pyproject.toml` file at the root" +msgstr "" + +#: ../../tutorials/installable-code.md:491 +msgid "A package directory containing an empty `__init__.py` file and" +msgstr "" + +#: ../../tutorials/installable-code.md:492 +msgid "At least one Python module (e.g. `add_numbers.py`)" +msgstr "" + +#: ../../tutorials/installable-code.md:494 +msgid "You are now ready to install (and build) your Python package!" +msgstr "" + +#: ../../tutorials/installable-code.md:496 +msgid "" +"While you can do this using hatch, we are going to use pip for this " +"lesson, so you can see how to install your tool into your preferred " +"environment." +msgstr "" + +#: ../../tutorials/installable-code.md:498 +msgid "" +"First open your preferred shell (Windows users may be using something " +"like gitbash) and `cd` into your project directory if you are not already" +" there." +msgstr "" + +#: ../../tutorials/installable-code.md:499 +msgid "Activate the Python environment that you wish to use." +msgstr "" + +#: ../../tutorials/installable-code.md:500 +msgid "Run `python -m pip install -e .`" +msgstr "" + +#: ../../tutorials/installable-code.md:503 +msgid "Add this back in when the lesson is published" +msgstr "" + +#: ../../tutorials/installable-code.md:504 +msgid "" +"Activate the Python environment that you wish to use. If you need help " +"with working with virtual environments check out this lesson (add link)." +msgstr "" + +#: ../../tutorials/installable-code.md:530 +msgid "What does `python -m pip install -e .` do?" +msgstr "" + +#: ../../tutorials/installable-code.md:533 +msgid "Let's break down `python -m pip install -e .`" +msgstr "" + +#: ../../tutorials/installable-code.md:535 +msgid "" +"`python -m pip install -e .` installs your package into the current " +"active Python environment in **editable mode** (`-e`). Installing your " +"package in editable mode, allows you to work on your code and then test " +"the updates interactively in your favorite Python interface. One " +"important caveat of editable mode is that every time you update your " +"code, you may need to restart Python." +msgstr "" + +#: ../../tutorials/installable-code.md:540 +msgid "" +"If you wish to install the package regularly (not in editable mode) you " +"can use:" +msgstr "" + +#: ../../tutorials/installable-code.md:543 +msgid "`python -m pip install . `" +msgstr "" + +#: ../../tutorials/installable-code.md:545 +msgid "**Using `python -m` when calling `pip`**" +msgstr "" + +#: ../../tutorials/installable-code.md:547 +msgid "" +"Above, you use`python -m` to call the version of pip installed into your " +"current active environment. `python -m` is important to ensure that you " +"are calling the version of pip installed in your current environment." +msgstr "" + +#: ../../tutorials/installable-code.md:552 +msgid "Look for pyospackage in your environment" +msgstr "" + +#: ../../tutorials/installable-code.md:554 +msgid "" +"Once you have installed your package, you can view it in your current " +"environment. If you are using `venv` or `conda`, `pip` list will allow " +"you to see your current package installations." +msgstr "" + +#: ../../tutorials/installable-code.md:558 +msgid "" +"Note that because pyospackage is installed in editable mode (`-e`) pip " +"will show you the directory path to your project's code" +msgstr "" + +#: ../../tutorials/installable-code.md:586 +msgid "Step 6: Test out your new package" +msgstr "" + +#: ../../tutorials/installable-code.md:588 +msgid "" +"After installing your package, type “python” at the command prompt in " +"your chosen terminal to start a Python session in your active Python " +"environment." +msgstr "" + +#: ../../tutorials/installable-code.md:591 +msgid "You can now import your package and access the `add_num` function." +msgstr "" + +#: ../../tutorials/installable-code.md:603 +msgid "Installing packages from GitHub" +msgstr "" + +#: ../../tutorials/installable-code.md:605 +msgid "" +"If you wish to share your code without publishing to PyPI you can always " +"install packages directly from GitHub using the syntax:" +msgstr "" + +#: ../../tutorials/installable-code.md:612 +msgid "To make your package GitHub installable, you can:" +msgstr "" + +#: ../../tutorials/installable-code.md:614 +msgid "Create a new GitHub repository" +msgstr "" + +#: ../../tutorials/installable-code.md:615 +msgid "" +"Push the contents of the project directory that you created above, to " +"GitHub" +msgstr "" + +#: ../../tutorials/installable-code.md:616 +msgid "" +"Finally install the package from GitHub using the command above. When you" +" use the command above, don't forget to substitute the user, repo, and " +"branch_or_tag with your specific values." +msgstr "" + +#: ../../tutorials/installable-code.md:618 +msgid "" +"For instance below you install the pyospackage from the main branch of " +"the pyOpenSci repository." +msgstr "" + +#: ../../tutorials/installable-code.md:621 +msgid "`python -m pip install git+https://github.com/user/repo.git@branch_or_tag`" +msgstr "" + +#: ../../tutorials/installable-code.md:625 +msgid "Congratulations! You created your first Python package" +msgstr "" + +#: ../../tutorials/installable-code.md:627 +msgid "" +"You did it! You have now created a Python package that you can install " +"into any Python environment." +msgstr "" + +#: ../../tutorials/installable-code.md:630 +msgid "In the upcoming lessons you will:" +msgstr "" + +#: ../../tutorials/installable-code.md:632 +msgid "" +"Learn how to [build and publish your Python package to (test) PyPI" +"](publish-pypi)" +msgstr "" + +#: ../../tutorials/installable-code.md:633 +msgid "Add a README file and LICENSE to your package" +msgstr "" + +#: ../../tutorials/installable-code.md:634 +msgid "" +"Add more metadata to your `pyproject.toml` file to support PyPI " +"publication." +msgstr "" + +#: ../../tutorials/installable-code.md:635 +msgid "learn how to publish to **conda-forge** from **PyPI**." +msgstr "" + +#: ../../tutorials/installable-code.md:637 +msgid "" +"Add a [README file](add-readme.md) and [LICENSE](add-license-coc.md) to " +"your package" +msgstr "" + +#: ../../tutorials/installable-code.md:638 +msgid "" +"[Add more metadata to your `pyproject.toml`](pyproject-toml.md) file to " +"support PyPI publication." +msgstr "" + +#: ../../tutorials/installable-code.md:639 +msgid "" +"[Learn how to build your package distribution](publish-pypi) files " +"(**sdist** and **wheel**) and publish to **test PyPI**." +msgstr "" + +#: ../../tutorials/installable-code.md:640 +msgid "" +"Finally you will learn how to [publish to **conda-forge**](publish-conda-" +"forge) from **PyPI**." +msgstr "" + +#: ../../tutorials/installable-code.md:644 +msgid "[Carpentries shell lesson](https://swcarpentry.github.io/shell-novice/)" +msgstr "" + +#: ../../tutorials/installable-code.md:646 +msgid "" +"[Python module " +"docs](https://docs.python.org/3/tutorial/modules.html#packages)" +msgstr "" + +#: ../../tutorials/installable-code.md:648 +msgid "[Numpy style docs](https://numpydoc.readthedocs.io/en/latest/format.html)" +msgstr "" + +#: ../../tutorials/installable-code.md:647 +msgid "[Google docstring style](https://google.github.io/styleguide/pyguide.html)" +msgstr "" + +#: ../../tutorials/installable-code.md:649 +msgid "[epydoc](https://epydoc.sourceforge.net/epytext.html)" +msgstr "" + +#: ../../tutorials/intro.md:27 +msgid "Python Packaging Tutorial Setup" +msgstr "" + +#: ../../tutorials/intro.md:34 ../../tutorials/intro.md:71 +msgid "What is a Python package?" +msgstr "" + +#: ../../tutorials/intro.md:34 +msgid "Make your code installable" +msgstr "" + +#: ../../tutorials/intro.md:34 +msgid "Publish to PyPI" +msgstr "" + +#: ../../tutorials/intro.md:34 +msgid "Publish to conda-forge" +msgstr "" + +#: ../../tutorials/intro.md:34 +msgid "Create and publish a Python Package" +msgstr "" + +#: ../../tutorials/intro.md:44 +msgid "Add README file" +msgstr "" + +#: ../../tutorials/intro.md:44 +msgid "Add a license & code of conduct" +msgstr "" + +#: ../../tutorials/intro.md:44 +msgid "Update metadata in pyproject.toml" +msgstr "" + +#: ../../tutorials/intro.md:44 +msgid "Project information files & metadata" +msgstr "" + +#: ../../tutorials/intro.md:53 +msgid "Migrate setup.py to a pyproject.toml using Hatch" +msgstr "" + +#: ../../tutorials/intro.md:53 +msgid "Hatch for Existing Packages" +msgstr "" + +#: ../../tutorials/intro.md:1 +msgid "Python packaging 101" +msgstr "" + +#: ../../tutorials/intro.md:3 +msgid "_A start to finish beginner-friendly tutorial_" +msgstr "" + +#: ../../tutorials/intro.md:5 +msgid "" +"Welcome to the pyOpenSci Python packaging tutorial series. The lessons on" +" the upcoming pages walk you through the core steps needed to create a " +"Python package." +msgstr "" + +#: ../../tutorials/intro.md:11 +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:13 +msgid "" +"This lesson is the first in a series of lessons to help you get started " +"with Python packaging." +msgstr "" + +#: ../../tutorials/intro.md:16 +msgid "Who are these tutorials for?" +msgstr "" + +#: ../../tutorials/intro.md:18 +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:23 +msgid "" +"In this series you will learn about the core elements that you need to " +"publish your package to the [Python Package Index " +"(PyPI)](https://pypi.org/)." +msgstr "" + +#: ../../tutorials/intro.md:25 +msgid "" +"In the second series, you will learn about infrastructure and " +"documentation needed to support package maintenance." +msgstr "" + +#: ../../tutorials/intro.md:60 ../../tutorials/publish-conda-forge.md:15 +#: ../../tutorials/publish-pypi.md:13 ../../tutorials/pyproject-toml.md:19 +#: ../../tutorials/setup-py-to-pyproject-toml.md:12 +msgid "Learning Objectives" +msgstr "" + +#: ../../tutorials/intro.md:62 +msgid "" +"This lesson introduces you to the basic components of a Python package. " +"After reading this lesson you will:" +msgstr "" + +#: ../../tutorials/intro.md:65 +msgid "Understand what a Python package is" +msgstr "" + +#: ../../tutorials/intro.md:66 +msgid "Be able to list the 5 core components of a Python package" +msgstr "" + +#: ../../tutorials/intro.md:67 +msgid "" +"Be able to explain the difference between generalizable code and code " +"that supports a specific scientific application" +msgstr "" + +#: ../../tutorials/intro.md:73 +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:76 +msgid "" +"A Python package is basically a directory with a specific file structure." +" Within the package directory structure, there are modules which are " +"files that end in `.py` (the same extension you'd see in a Python " +"script). These modules allow you to group and structure your Python code." +" Each module contains functions and classes, that you can think about as " +"the tools in your toolbox." +msgstr "" + +#: ../../tutorials/intro.md:85 +msgid "" +"Diagram showing a sketch of a toolbox filled with different tools " +"including a hammer and a saw." +msgstr "" + +#: ../../tutorials/intro.md:87 +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:92 +msgid "Python packages are installable" +msgstr "" + +#: ../../tutorials/intro.md:94 +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:103 +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:108 +msgid "Why create a Python package?" +msgstr "" + +#: ../../tutorials/intro.md:110 +msgid "You might create a Python package because you want to:" +msgstr "" + +#: ../../tutorials/intro.md:112 +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:113 +msgid "" +"**Share your code:** If you publish a package on a public repository such" +" as PyPI or conda, your package can be installed on any machine using pip" +" or conda with a single command." +msgstr "" + +#: ../../tutorials/intro.md:114 +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:115 +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:117 +msgid "What to consider before you create a package" +msgstr "" + +#: ../../tutorials/intro.md:119 +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:122 +msgid "Who you think will use your package" +msgstr "" + +#: ../../tutorials/intro.md:123 +msgid "How people might use your package and on what data (if data are relevant)" +msgstr "" + +#: ../../tutorials/intro.md:124 +msgid "Whether you have time to add things such as documentation and tests" +msgstr "" + +#: ../../tutorials/intro.md:125 +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:127 +msgid "" +"Before creating a user-facing package, it's important to consider all of " +"the above." +msgstr "" + +#: ../../tutorials/intro.md:129 +msgid "The elements of a Python package" +msgstr "" + +#: ../../tutorials/intro.md:133 ../../tutorials/intro.md:211 +msgid "Diagram showing .. more here if this stays." +msgstr "" + +#: ../../tutorials/intro.md:135 +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:141 +msgid "The core elements of Python package include:" +msgstr "" + +#: ../../tutorials/intro.md:143 +msgid "" +"**Code:** Functions and classes that provide functionality for a user of " +"your package" +msgstr "" + +#: ../../tutorials/intro.md:144 +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:145 +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:146 +msgid "" +"Development Documentation helps both maintainers and contributors " +"understand how to maintain a package's infrastructure." +msgstr "" + +#: ../../tutorials/intro.md:147 +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:148 +msgid "" +"**License:** An open source license, or license that is [OSI " +"approved](https://opensource.org/licenses/), refers to an license that " +"allows others to use your package. It also provides legal direction " +"regarding how elements of the package can and can't be reused." +msgstr "" + +#: ../../tutorials/intro.md:149 +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:151 +msgid "What pyOpenSci looks for in a package" +msgstr "" + +#: ../../tutorials/intro.md:154 +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:160 +msgid "Packages are more than just code - Infrastructure" +msgstr "" + +#: ../../tutorials/intro.md:162 +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:167 +msgid "Version control and storing your package on GitHub or GitLab" +msgstr "" + +#: ../../tutorials/intro.md:169 +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:174 +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:176 +msgid "GitHub & GitLab vs. Git" +msgstr "" + +#: ../../tutorials/intro.md:179 +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:184 +msgid "Issues or Ticket Trackers" +msgstr "" + +#: ../../tutorials/intro.md:186 +msgid "" +"GitHub and GitLab also both offer community features such as issues that " +"allow:" +msgstr "" + +#: ../../tutorials/intro.md:188 +msgid "you to communicate with your maintainers and contributor community" +msgstr "" + +#: ../../tutorials/intro.md:189 +msgid "users to report bugs, ask questions and request new features" +msgstr "" + +#: ../../tutorials/intro.md:190 +msgid "" +"you to publicly keep track of enhancements and features you want to work " +"on for your package." +msgstr "" + +#: ../../tutorials/intro.md:192 +msgid "Continuous integration and continuous deployment" +msgstr "" + +#: ../../tutorials/intro.md:194 +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:196 +msgid "**An example of Continuous integration:**" +msgstr "" + +#: ../../tutorials/intro.md:198 +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:200 +msgid "**An example of Continuous deployment:**" +msgstr "" + +#: ../../tutorials/intro.md:202 +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:204 +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:213 +msgid "The lifecycle of a scientific Python package." +msgstr "" + +#: ../../tutorials/intro.md:216 +msgid "When should you turn your code into a Python package?" +msgstr "" + +#: ../../tutorials/intro.md:218 +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:220 +msgid "There are a few use cases to consider:" +msgstr "" + +#: ../../tutorials/intro.md:222 +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:224 +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:227 +msgid "LINK to pip installable lesson when it's published - it's in review now" +msgstr "" + +#: ../../tutorials/intro.md:230 +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:233 +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:235 +msgid "Packages that you expect others to use should be well-scoped" +msgstr "" + +#: ../../tutorials/intro.md:237 +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:239 +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:241 +msgid "How does this relate to code for a research project?" +msgstr "" + +#: ../../tutorials/intro.md:244 +msgid "" +"A [Research Compendium](https://the-turing-way.netlify.app/reproducible-" +"research/compendia.html) is an organized set of code, data and " +"documentation that supports a specific research project. It aims to " +"enhance the reproducibility and transparency of research by providing a " +"comprehensive record of the methods, data, and analyses used in a study." +msgstr "" + +#: ../../tutorials/intro.md:249 +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:254 +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:255 +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:258 +msgid "Below are a few examples well scoped pyOpenSci packages:" +msgstr "" + +#: ../../tutorials/intro.md:260 +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:261 +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:263 +msgid "Matplotlib as an example" +msgstr "" + +#: ../../tutorials/intro.md:265 +msgid "" +"At the larger end of the user spectrum, Matplotlib is a great example. " +"Matplotlib does one thing really well:" +msgstr "" + +#: ../../tutorials/intro.md:268 +msgid "_It creates visual plots of data._" +msgstr "" + +#: ../../tutorials/intro.md:270 +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:276 +msgid "Code should also be clean & readable & documented" +msgstr "" + +#: ../../tutorials/intro.md:278 +msgid "" +"The code in your package should also be clean, readable, and well " +"documented." +msgstr "" + +#: ../../tutorials/intro.md:280 +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:284 +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:288 +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:292 +msgid "Making your package installable - publishing to PyPI & conda-forge" +msgstr "" + +#: ../../tutorials/intro.md:294 +msgid "Python packages and environments" +msgstr "" + +#: ../../tutorials/intro.md:296 +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:302 +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:304 +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:311 +msgid "Publishing a package to PyPI / Conda-Forge" +msgstr "" + +#: ../../tutorials/intro.md:313 +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:317 +msgid "" +"Learn [how to publish your package to PyPI in this tutorial.](publish-" +"pypi.md)" +msgstr "" + +#: ../../tutorials/intro.md:319 +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:321 +msgid "" +"[You will learn more about the conda-forge publication process here" +".](publish-conda-forge.md)" +msgstr "" + +#: ../../tutorials/intro.md:324 +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:326 +msgid "" +"In the image above, you can see the steps associated with publishing your" +" package on PyPI and conda-forge. Note that the distribution files that " +"PyPI requires are the [sdist](#python-source-distribution) and [wheel" +"](#python-wheel) files. Once you are ready to make your code publicly " +"installable, you can publish it on PyPI. Once your code is on PyPI it is " +"straight forward to then publish to conda-forge. You create a recipe " +"using the Grayskull package and then you open a pr in the conda-forge " +"recipe repository. You will learn more about this process in the [conda-" +"forge lesson](/tutorials/publish-conda-forge)." +msgstr "" + +#: ../../tutorials/intro.md:330 +msgid "Yay, your package has users! Now what?" +msgstr "" + +#: ../../tutorials/intro.md:332 +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:334 +msgid "To support your community, you'll want to add things like:" +msgstr "" + +#: ../../tutorials/intro.md:336 +msgid "" +"[a development guide that documents your maintainer workflow process " +"](/documentation/repository-files/development-guide.md)" +msgstr "" + +#: ../../tutorials/intro.md:337 +msgid "" +"[a code of conduct to defines community interaction standards and " +"expectations](/documentation/repository-files/code-of-conduct-file.md)" +msgstr "" + +#: ../../tutorials/intro.md:338 +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:340 +msgid "Support for contributors and maintainers" +msgstr "" + +#: ../../tutorials/intro.md:342 +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:344 +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:349 +msgid "What's next?" +msgstr "" + +#: ../../tutorials/intro.md:351 +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:353 +msgid "" +"In this next lesson you will learn how to create a basic installable " +"Python package. Make your code pip installable " +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:1 +msgid "Publish your Python package that is on PyPI to conda-forge" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:3 +msgid "In the previous lessons, you've learned:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:5 +msgid "" +"How to [create the most basic version of a Python package](installable-" +"code.md). This entailed making your code installable." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:6 +msgid "[How to publish your Python package to PyPI](publish-pypi)" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:7 +msgid "How to add a `README` and `LICENSE` file to your package" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:8 +msgid "" +"How to setup your `pyproject.toml` file with all of the metadata that " +"PyPI requires and also metadata that will be helpful for users to find " +"your package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:10 +msgid "" +"If you have gone through all of the above lessons, you are now ready to " +"publish your package on conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:13 +msgid "" +"**IMPORTANT:** Please do not practice publishing your package to conda-" +"forge. You should only publish to conda-forge when you have a package on " +"pypi.org that you plan to maintain." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:19 ../../tutorials/publish-pypi.md:17 +msgid "In this lesson you will learn how to:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:21 +msgid "Create a conda-forge yaml recipe for your package using Grayskull" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:22 +msgid "" +"Submit the recipe (yaml file) to the conda-forge staged recipes " +"repository as a pull request" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:23 +msgid "" +"Maintain your conda-forge package by creating new releases for your " +"package on PyPI" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:26 +msgid "" +"Once your package is on PyPI you can then easily publish it to conda-" +"forge using the [grayskull](https://conda.github.io/grayskull/) tool. You" +" do not need to build the package specifically for conda, conda-forge " +"will build from your PyPI source distribution file (sdist)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:33 +msgid "" +"Image showing the progression of creating a Python package, building it " +"and then publishing to PyPI and conda-forge. You take your code and turn " +"it into distribution files (sdist and wheel) that PyPI accepts. then " +"there is an arrow towards the PyPI repository where ou publish both " +"distributions. From PyPI if you create a conda-forge recipe you can then " +"publish to conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:35 +msgid "" +"Once you have published both package distributions (the source " +"distribution and the wheel) to PyPI, you can then publish to conda-forge." +" Conda-forge requires a source distribution on PyPI in order to build " +"your package on conda-forge. You do not need to rebuild your package to " +"publish to conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:38 +msgid "What is conda-forge?" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:40 +msgid "" +"conda is an open source package and environment management tool that can " +"be used to install tools from the different channels on Anaconda.org." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:43 +msgid "" +"You can think about a channel as a specific location where a group of " +"packages are stored and can be installed from using a command such as " +"`conda install packagename`. In the case of conda channels, some of these" +" channels such as the `defaults` channel, is managed by Anaconda (the " +"company). Only Anaconda can decide what packages are available in the " +"`defaults` channel. However, the conda-forge (and bioconda) channel are " +"community-managed channels. Anyone can submit a package to these channels" +" however they must pass a technical review in the [staged-recipes GitHub " +"repository](https://github.com/conda-forge/staged-recipes) to be " +"published." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:46 +msgid "[Learn more about conda channels here.](#about-conda)" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:50 +msgid "" +"Graphic with the title Python package repositories. Below it says " +"anything hosted on PyPI can be installed using pip install. Packaging " +"hosted on a conda channel can be installed using conda install. Below " +"that there are two rows. The top row says conda channels. Next to it are " +"three boxes one with conda-forge, community maintained; bioconda and then" +" default - managed by the Anaconda team. Below that there is a row that " +"says PyPI servers. PyPI - anyone can publish to PyPI and test PyPI (a " +"testbed server for you to practice)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:52 +msgid "" +"Conda channels represent various repositories that you can install " +"packages from. Because conda-forge is community maintained, anyone can " +"submit a recipe there. PyPI is also a community maintained repository. " +"Anyone can submit a package to PyPI and test PyPI. Unlike conda-forge " +"there are no manual checks of packages submitted to PyPI." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:55 +msgid "Why publish to conda-forge" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:57 +msgid "" +"There are many users, especially in the scientific Python ecosystem that " +"use conda as their primary package manager / environment tool. Thus, " +"having packages available to these users on the conda-forge channel is " +"useful. In some cases packages on conda-forge can minimize dependency " +"conflicts that can occur when mixing installations using pip and conda. " +"This is particularly important for the spatial ecosystem." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:59 +msgid "How publishing to conda-forge works" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:61 +msgid "" +"Once you have built and published your package to PyPI, you have " +"everything that you need to publish to conda-forge. There is no " +"additional build step needed to publish to conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:63 +msgid "" +"Conda-forge will build your package from the source distribution which " +"you [published to PyPI in the previous lesson](publish-pypi) using the " +"recipe that you will create below." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:65 +msgid "Conda-forge publication steps" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:68 +msgid "" +"Image showing the steps associated with publishing to conda-forge. Check " +"out the caption below for a detailed description." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:70 +msgid "" +"The steps for publishing to conda-forge begin with publishing your Python" +" package to PyPI. Once you have published to PyPI you can then create a " +"yaml file recipe that can be submitted to the conda-forge staged recipes " +"repository for review. Once that recipe is accepted, your package will " +"get it's on repository (known as a feedstock) on conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:73 +msgid "The steps to publish to conda-forge are:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:75 +msgid "Publish your Python package distribution files (sdist & wheel) to PyPI" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:76 +msgid "" +"Create a conda-forge recipe, which is a yaml file with instructions on " +"how to build your package on conda-forge, using the grayskull[^grayskull]" +" package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:77 +msgid "" +"Submit the recipe (yaml file) to the conda-forge staged recipes " +"repository as a pull request for review. [Click here for an example " +"submission from pyOpenSci.](https://github.com/conda-forge/staged-" +"recipes/pull/25173)" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:79 +msgid "" +"Once someone from the conda-forge team reviews your pull request, you may" +" need to make some changes. Eventually the pull request will be approved " +"and merged." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:81 +msgid "" +"Once your recipe is accepted and merged on conda-forge, users can install" +" your package using:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:83 +msgid "`conda install -c conda-forge your-package`" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:85 +msgid "" +"You only create the recipe once. Once the recipe is accepted and merged, " +"you only need to maintain the repository." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:87 +msgid "Maintaining a conda-forge package" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:89 +msgid "" +"Once your package is on conda-forge, the repository will track release " +"activity on the package's PyPI repository. Any time you make a new PyPI " +"release with a new source distribution, conda-forge will build and update" +" your conda-forge repository (also known as a feedstock)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:91 +msgid "" +"When the update is processed, the friendly conda-forge bot will create a " +"new pull request with an updated distribution recipe in your feedstock." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:93 +msgid "" +"You can review that pull request and then merge it once all of the " +"continuous integration tests pass." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:95 +msgid "" +" How to Publish your package" +" on conda-forge" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:97 +msgid "" +"It's time to add your package to the conda-forge channel. Remember that " +"your package needs to be on PyPI before the steps below will work. And " +"also remember that the team managing conda-forge are all volunteers." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:100 +msgid "" +"Be sure that your package is on PyPI.org (not test.pypi.org) before you " +"attempt to publish to conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:103 +msgid "" +"Only submit your package to conda-forge if you intend to maintain it over" +" time." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:106 +msgid "" +"Note - this is a tutorial aimed to help you get your package onto conda-" +"forge. The official conda documentation for this processed [is " +"here](https://conda-forge.org/docs/maintainer/adding_pkgs.html)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:108 +msgid "Step 1: Install grayskull" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:110 +msgid "" +"First, [install " +"grayskull](https://conda.github.io/grayskull/user_guide.html). You can " +"install it using either pip:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:116 +msgid "or conda" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:122 +msgid "" +"To run this command, use the same shell / terminal that you have been " +"using to run hatch commands in the previous tutorials." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:127 +msgid "" +"You can also install grayskull using pipx[^pipx]. pipx is a tool that " +"allows you to install commonly used tools that you might want to have " +"available across multiple Python environments rather than installing the " +"package into every Python environment that ou create." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:130 +msgid "Step 2: Fork and clone the conda-forge staged-recipes repository" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:132 +msgid "" +"Next, open your shell and `cd` to a location where you want to clone the " +"**conda-forge/staged-recipes** repository." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:133 +msgid "" +"fork and clone the [conda-forge/staged-recipes GitHub " +"repository](https://github.com/conda-forge/staged-recipes)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:134 +msgid "" +"Create a new branch in your fork rather than submitting from the main " +"branch of your fork. We suggest naming the branch your package's name." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:136 +msgid "`git checkout -b your-package-name `" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:138 +msgid "In bash, `cd` into the `staged-recipes/recipes` folder" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:146 +msgid "" +"Next, create a new branch in your `conda-forge/staged-recipes` cloned " +"repository. You might want to make that branch the same name as your " +"package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:157 +msgid "Step 3: Create your conda-forge recipe" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:159 +msgid "Next, navigate to the recipes directory" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:161 +msgid "" +"If you run `ls` here, you will notice there is an example directory with " +"an example recipe for you to look at." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:173 +msgid "Next, run `grayskull pypi your-package-name` to generate a recipe." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:217 +msgid "" +"Grayskull will pull metadata about your package from PyPI. It does not " +"use your local installation of the package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:218 +msgid "" +"An internet connection is needed to run the `grayskull pypi your-package-" +"name` step." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:221 +msgid "" +"When you run grayskull, it will grab the latest distribution of your " +"package from PyPI and will use that to create a new recipe." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:223 +msgid "" +"The recipe will be saved in a directory named after your package's name, " +"wherever you run the command." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:225 +msgid "`recipes/packagename/meta.yaml`" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:227 +msgid "" +"At the very bottom of the grayskull output, it will also tell you where " +"it saved the recipe file." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:230 +msgid "" +"Open the meta.yaml file. The finished `meta.yaml` file that grayskull " +"creates should look like the example below:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:277 +msgid "Step 3b: Bug fix - add a home url to the about: section" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:279 +msgid "" +"There is currently a small bug in Grayskull where it doesn't populate the" +" home: element of the recipe. if you don't include this, [you will " +"receive an error message](https://github.com/conda-forge/staged-" +"recipes/pull/25173#issuecomment-1917916528) from the friendly conda-forge" +" linter bot." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:293 +msgid "to fix this, open your meta.yaml file in your favorite text editor." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:294 +msgid "and add a home: element to the about section" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:296 +msgid "The about section will look like this after you create your recipe." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:306 +msgid "" +"Below you add a home: element. If you have a project home page / website " +"you can use that url. Otherwise, you can also use your PyPI landing page." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:317 +msgid "Step 4: tests for conda-forge" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:319 +msgid "" +"Next, have a look at the tests section in your **meta.yaml** file. At a " +"minimum you should import your package or the main modules associated " +"with your package and run `pip check`." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:321 +msgid "" +"`pip check` will ensure that your package installs properly with all of " +"the proper dependencies." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:333 +msgid "" +"If you have more advanced tests that you wish to run, you can add them " +"here. However, you can also simply leave the tests section as it is." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:335 +msgid "Step 4: Submit a pull request to the staged-recipes repository" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:337 +msgid "" +"Once you have completed all of the above, you are ready to open up a pull" +" request in the `conda-forge/staged-recipes repository`." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:339 +msgid "" +"Submit a pull request from your fork/branch of the staged-recipes " +"repository." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:340 +msgid "" +"Remember that the conda-forge maintainers are volunteers. Be patient for " +"someone to respond and supportive in your communication with them." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md +msgid "Conda-forge checklist help" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:346 +msgid "Conda-forge Staged-recipes Pull Request Checklist" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:348 +msgid "" +"When you submit your package to conda-forge, the pull request template " +"includes a list of checks that you want to ensure you have covered." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:350 +msgid "Below we break down each element of that list." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:352 +msgid "Pull request template checklist tips" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:355 +msgid "" +"-[x] Title of this PR is meaningful: e.g. \"Adding my_nifty_package\", " +"not \"updated meta.yaml\"." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:357 +msgid "" +"**Translation:** Make sure that your pull request title is specific. We " +"suggest something like: `Add recipe for `" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:360 +msgid "" +"-[x] License file is packaged (see [here](https://github.com/conda-forge" +"/staged-" +"recipes/blob/5eddbd7fc9d1502169089da06c3688d9759be978/recipes/example/meta.yaml#L64-L73)" +" for an example)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:362 +msgid "" +"**Translation:** You should have a LICENSE file included in your " +"package's source distribution. If you have followed the pyOpenSci " +"tutorials then you already have a LICENSE file and are likely using the " +"MIT license. When you run `hatch build`, it will bundle that file into " +"the output [source distribution file (which is the tar.gz file)](python-" +"source-distribution) that conda-forge will use to build your package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:364 +msgid "[x] Source is from official source." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:366 +msgid "" +"**Translation:** If your package is on PyPI as you learned in the " +"[previous lesson on publishing your Python package](publish-pypi) then " +"you are in good shape. conda-forge prefers that your distribution is " +"published to a known repository." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:368 +msgid "" +"-[x] Package does not vendor other packages. (If a package uses the " +"source of another package, they should be separate packages or the " +"licenses of all packages need to be packaged)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:370 +msgid "" +"**Translation:** If the code base in your package is your own and it all " +"shares the same LICENSE then you are in good shape. If you have code " +"taken from other packages then you may need to declare that and include " +"licenses for that code if it is different. If you followed these " +"tutorials then you do not have any vendored code." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:372 +msgid "" +"-[x] If static libraries are linked in, the license of the static library" +" is packaged." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:374 +msgid "" +"-[x] Package does not ship static libraries. If static libraries are " +"needed, [follow CFEP-18](https://github.com/conda-" +"forge/cfep/blob/main/cfep-18.md)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:376 +msgid "" +"**Translation:** A static library refers to a copy of a package built " +"into your package. If your package is a pure Python package, then you can" +" check that your package does not ship static libraries as this does not " +"apply to you." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:378 +msgid "" +"The pyOpenSci tutorials are all pure Python and as such do not use static" +" libraries in a linked or shipped (included in the package distribution) " +"format." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:380 +msgid "" +"If your package has a more complex build that includes links to " +"extensions written in other languages such as C++, then be sure to " +"include the proper licenses for those extensions in your metadata." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:385 +msgid "" +"If you want to learn more about static libraries, then [this " +"overview](https://pypackaging-" +"native.github.io/background/compilation_concepts/#shared-vs-static-" +"libraries) might help." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:388 +msgid "-[ ] Build number is 0." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:390 +msgid "" +"**Translation:** The build number in your recipe is right below the " +"source location of your package's source distribution. `number: 0` is " +"what you should see in that section of your recipe." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:403 +msgid "" +"[x] A tarball (`url`) rather than a repo (e.g. `git_url`) is used in your" +" recipe (see [here](https://conda-" +"forge.org/docs/maintainer/adding_pkgs.html) for more details)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:405 +msgid "" +"**Translation:** Here conda wants you to provide a link to the source " +"distribution on PyPI rather than a link to your GitHub repository " +"distribution. Notice above in the Source section of your recipe there is " +"a `url:` section that provides a PyPI url that ends in tar.gz. That is a " +"link to your source distribution that conda-forge will use." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:411 +msgid "" +"[x] GitHub users listed in the maintainer section have posted a comment " +"confirming they are willing to be listed there." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:413 +msgid "" +"**Translation** Once you have submitted your recipe, be sure that all " +"maintainers listed in your recipe respond acknowledging that they are ok " +"with being listed as a maintainer for the conda-forge version of your " +"package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:415 +msgid "" +"[x] When in trouble, please check our [knowledge base " +"documentation](https://conda-" +"forge.org/docs/maintainer/knowledge_base.html) before pinging a team." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:417 +msgid "" +"**Translation** The conda team are volunteers who spend their time " +"supporting our community. Please try to troubleshoot on your own first " +"before tagging one of them for help." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:419 +msgid "" +"This is also why we don't suggest you publish to conda-forge as a " +"practice run." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:423 +msgid "" +"Once you create your pull request, a suite of CI actions will run that " +"build and test the build of your package. A conda-forge maintainer will " +"work with you to get your recipe in good shape and merged." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:427 +msgid "" +"Image showing the 5 CI tasks that will run against your package in the " +"GitHub interface after you'ce created a pull request." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:429 +msgid "" +"Wait until all of the CI steps in your pull request have run. At that " +"point your pull request is ready for review by a conda-forge maintainer." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:432 +msgid "" +"In some cases getting all of the checks to run successfully in CI might " +"take a bit of work. If you are struggling to get your recipe to build " +"properly, you can ping the conda-forge maintainer team for help." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:434 +msgid "Please be patient and wait for them to respond." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:436 +msgid "conda-forge staged recipes and CI failures" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:439 +msgid "" +"If your package is a pure Python package that can be installed on any " +"type of computer (Windows, mac, linux) and has no architecture " +"requirements (known as noarch: Python or no architecture requirements) " +"then the conda-forge team only requires tests for Linux CI to pass." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:441 +msgid "" +"So if tests for Windows and MAC OS fail, that is to be expected. In this " +"case, don't worry about failing tests, the maintainer team can help you " +"get your package published." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:444 +msgid "" +"Once you have submitted your recipe, you can wait for the CI build to " +"pass. If it's not passing, and you aren't sure why, a conda-forge " +"maintainer can likely help you figure things out." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:446 +msgid "" +"Once your recipe is built and merged, the conda team will create a new " +"package repository for you similar to [this one for the GemGIS " +"package](https://github.com/conda-forge/gemgis-feedstock)." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:448 +msgid "" +" Congratulations - you " +"have added your package to conda-forge." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:450 +msgid "" +"The last part of this process is maintaining the repository. We cover " +"that next." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:453 +msgid "Maintaining your conda-forge feedstock" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:455 +msgid "" +"Every time you create a new release on PyPI, the conda-forge bots will " +"recognize the release and will rebuild the newly released version of your" +" package. This process may take a day or two to complete so be patient." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:457 +msgid "" +"Once the conda-forge build is complete, all of the maintainers of your " +"conda-forge feedstock will get a ping on GitHub that a new pull request " +"has been opened." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:459 +msgid "" +"Review the pull request. If all tests are passing, you can merge it. " +"Shortly after merging your pull request, the conda-forge release will be " +"available for users to install:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:461 +msgid "`conda install -c conda-forge yourpackage`" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:465 +msgid "If you have walked through this entire tutorial series you will now:" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:467 +msgid "Understand [what a Python package is ](intro.md)" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:468 +msgid "" +"Know how to [make your code installable](installable-code.md) into Python" +" environments" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:469 +msgid "" +"Know how to create a `pyproject.toml` file, a `README` file, and a " +"`LICENSE` and code of conduct." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:470 +msgid "Know how to [publish your package to PyPI](publish-pypi.md) and" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:471 +msgid "Know how to publish your package to conda-forge" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:473 +msgid "" +"The above are the basic steps that you need to take to create and publish" +" a Python package. In a future tutorial series we will cover that basics " +"of maintaining your package." +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:477 +msgid "[Grayskull blogpost](https://conda-forge.org/blog/2020/03/05/grayskull/)" +msgstr "" + +#: ../../tutorials/publish-conda-forge.md:478 +msgid "[Pipx documentation](https://pipx.pypa.io/stable/)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:1 +msgid "Publish your Python package to PyPI" +msgstr "" + +#: ../../tutorials/publish-pypi.md:4 +msgid "" +"Make sure they add /dist to their .gitignore file. We have not discussed " +"GitHub workflows anywhere yet. Where does that fit?" +msgstr "" + +#: ../../tutorials/publish-pypi.md:8 +msgid "In the previous Python packaging lessons, you've learned:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:10 +msgid "What a Python package is" +msgstr "" + +#: ../../tutorials/publish-pypi.md:11 +msgid "How to make your code installable." +msgstr "" + +#: ../../tutorials/publish-pypi.md:19 +msgid "Build your package's source (sdist) and wheel distributions" +msgstr "" + +#: ../../tutorials/publish-pypi.md:20 +msgid "Setup an account on TestPyPI (the process is similar for PyPI)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:21 +msgid "Publish your package to TestPyPI and PyPI" +msgstr "" + +#: ../../tutorials/publish-pypi.md:23 +msgid "" +"You will do all of your development work in this lesson using " +"[Hatch](https://hatch.pypa.io/latest/)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:25 +msgid "" +"Once your package is on PyPI you can publish it to conda-forge (which is " +"a channel on conda) using " +"[Grayskull](https://conda.github.io/grayskull/)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:28 +msgid "" +"You will learn how to publish to conda-forge in the [next lesson" +"](publish-conda-forge)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:32 +msgid "" +"Graphic showing the high level packaging workflow. On the left you see a " +"graphic with code, metadata and tests in it. Those items all go into your" +" package. An arrow to the right takes you to a build distribution files " +"box. Another arrow to the right takes you to a publish to PyPI box which " +"has an arrow containing sdist and wheel that notes those files go to PyPI" +" for hosting. From PyPI is an arrow containing sdist since you can then " +"connect to conda-forge for an automated build that sends distributions " +"from PyPI to conda-forge." +msgstr "" + +#: ../../tutorials/publish-pypi.md:34 +msgid "" +"You need to build your Python package in order to publish it to PyPI (or " +"Conda). The build process organizes your code and metadata into a " +"distribution format that can be uploaded to PyPI and subsequently " +"downloaded and installed by users." +msgstr "" + +#: ../../tutorials/publish-pypi.md:37 +msgid "TestPyPI vs PyPI" +msgstr "" + +#: ../../tutorials/publish-pypi.md:39 +msgid "" +"There are two repositories associated with PyPI to which you can upload " +"your Python package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:42 +msgid "" +"**[TestPyPI](https://test.pypi.org):** TestPyPI is a package repository " +"provided by PyPI that you can use for testing that your package can be " +"uploaded, downloaded, and installed correctly. This is a great place to " +"practice and learn how to publish a package without exposing your " +"incomplete package on the real PyPI service." +msgstr "" + +#: ../../tutorials/publish-pypi.md:43 +msgid "" +"**[PyPI](https://pypi.org):** This is the live, production PyPI " +"repository where you can officially publish your Python package, and from" +" which users will get your package. IMPORTANT: Only publish your package " +"to PyPI when you are ready for it to be used by others and/or confident " +"that it will become a package that you will maintain. PyPI is not a place" +" to practice learning how to publish a Python package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:45 +msgid "" +"The steps for publishing on TestPyPI vs. PyPI are similar with the " +"exception of a different url. We will point out where they differ." +msgstr "" + +#: ../../tutorials/publish-pypi.md:48 +msgid "4 Steps for publishing a Python package on TestPyPI (or PyPI)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:50 +msgid "" +"In this lesson you will learn how to publish your package to TestPyPI " +"using [Hatch](https://hatch.pypa.io/latest/). There are 4 things that you" +" need to do to publish your Python package: to TestPyPI. You need to:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:55 +msgid "**Create a package development environment**" +msgstr "" + +#: ../../tutorials/publish-pypi.md:56 +msgid "" +"[**Build your package using `hatch build`**](../package-structure-code" +"/python-package-distribution-files-sdist-wheel). Building a package is " +"the process of turning your code into two types of distribution files: " +"sdist and wheel. The wheel distribution file is particularly important " +"for users who will `pip install` your package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:57 +msgid "" +"**Create an account on TestPyPI (or PyPI)**: You will need to create a " +"TestPyPI account and associated token which provides permissions for you " +"to upload your package. When you later publish your package to PyPI, you " +"will need a separate PyPI account and token." +msgstr "" + +#: ../../tutorials/publish-pypi.md:58 +msgid "**Publish to TestPyPI using `hatch publish`**" +msgstr "" + +#: ../../tutorials/publish-pypi.md:60 +msgid "" +"In a future lesson, you will learn how to create an automated GitHub " +"action workflow that publishes an updated version of your package to PyPI" +" every time you create a GitHub release." +msgstr "" + +#: ../../tutorials/publish-pypi.md:64 +msgid "Learn more about building Python packages in our guide" +msgstr "" + +#: ../../tutorials/publish-pypi.md:68 +msgid "" +"[Learn more about what building a Python package is](../package-" +"structure-code/python-package-distribution-files-sdist-wheel)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:69 +msgid "" +"[Learn more about the package distribution file that PyPI needs called " +"the wheel](#python-wheel)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:70 +msgid "" +"[Learn more about the package distribution file that conda-forge will " +"need on PyPI called the sdist (source distribution)](#python-source-" +"distribution)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:73 +msgid "Step 1: Create a Python package development environment" +msgstr "" + +#: ../../tutorials/publish-pypi.md:75 +msgid "" +"The first step in building your package is to create a development " +"environment. The Python environment will contain all of the dependencies " +"needed to both install and work on your package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:77 +msgid "Use Hatch to create your environment." +msgstr "" + +#: ../../tutorials/publish-pypi.md:85 +msgid "Then view all of the current environments that hatch has access to:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:97 +msgid "" +"Then activate the environment. Note that when you call a shell from a " +"Hatch environment, it will automatically install your package into the " +"environment in development or editable mode." +msgstr "" + +#: ../../tutorials/publish-pypi.md:107 +msgid "View what's in the environment using `pip list`:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:123 +msgid "At any time you can exit the environment using `exit`." +msgstr "" + +#: ../../tutorials/publish-pypi.md:137 +msgid "Hatch and environments" +msgstr "" + +#: ../../tutorials/publish-pypi.md:139 +msgid "" +"Behind the scenes when hatch creates a new virtual environment, by " +"default it uses venv[^venv] which is the default environment management " +"tool that comes with Python installations." +msgstr "" + +#: ../../tutorials/publish-pypi.md:142 +msgid "Hatch will:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:144 +msgid "Create a new virtualenv (venv) that is located on your computer." +msgstr "" + +#: ../../tutorials/publish-pypi.md:145 +msgid "" +"Install your package into the environment in editable mode (similar to " +"`python -m pip install -e`). This means it installs both your project and" +" your project's dependencies as declared in your pyproject.toml file." +msgstr "" + +#: ../../tutorials/publish-pypi.md:147 +msgid "Step 2: Build your package's sdist and wheel distributions" +msgstr "" + +#: ../../tutorials/publish-pypi.md:149 +msgid "" +"Once you have your development environment setup, you are ready to build " +"your package using Hatch. Remember that building is the process of " +"turning your Python package file structure into two distribution files:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:151 +msgid "" +"The [wheel distribution](#python-wheel) is a pre-built version of your " +"package. It useful for users as it can be directly installed using a tool" +" such as `pip`. This file has the extension `.whl`." +msgstr "" + +#: ../../tutorials/publish-pypi.md:152 +msgid "" +"The [source distribution](#python-source-distribution) contains the files" +" that make up your package in an unbuilt format. This file will have the " +"extension `.tar.gz`." +msgstr "" + +#: ../../tutorials/publish-pypi.md:154 +msgid "" +"You will use Hatch as a **Front end** tool that builds your package's " +"sdist and wheel using the [hatchling](https://hatch.pypa.io/latest/) " +"build back-end. The hatchling build back-end is used because you declared" +" it in your pyproject.toml file in the [previous lesson](installable-" +"code)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:158 +msgid "To build your package run `hatch build`:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:169 +msgid "Learn more about building a Python package" +msgstr "" + +#: ../../tutorials/publish-pypi.md:171 +msgid "" +"You can learn more about building in the [build page of our packaging " +"guide](../package-structure-code/python-package-distribution-files-sdist-" +"wheel)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:175 +msgid "" +"The sdist is important if you wish to [publish your package to conda-" +"forge](publish-conda-forge). You will learn about this in a later lesson." +msgstr "" + +#: ../../tutorials/publish-pypi.md:179 +msgid "" +"➜ hatch build ────────────────────────────────────── sdist " +"────────────────────────────────────── dist/pyospackage-0.1.tar.gz " +"────────────────────────────────────── wheel " +"────────────────────────────────────── dist/pyospackage-0.1-py3-none-" +"any.whl" +msgstr "" + +#: ../../tutorials/publish-pypi.md:186 +msgid "" +" Congratulations - " +"you've created your Python package distribution files " +msgstr "" + +#: ../../tutorials/publish-pypi.md:188 +msgid "" +"You've now built your Python package and created your package " +"distribution files. The next step is to setup your account on TestPyPI so" +" you can publish your package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:191 +msgid "Step 3. Setup your TestPyPI account" +msgstr "" + +#: ../../tutorials/publish-pypi.md:193 +msgid "" +"Next, you'll setup an account on TestPyPI. Remember that you are using " +"TestPyPI here instead of the real PyPI as a way to safely learn how to " +"publish a package without accidentally \"releasing\" your package before " +"it's ready." +msgstr "" + +#: ../../tutorials/publish-pypi.md:197 +msgid "TestPyPI vs. PyPI" +msgstr "" + +#: ../../tutorials/publish-pypi.md:198 +msgid "" +"If you have a package that you are confident belongs on PyPI, all of the " +"steps below will also work for you. When you publish using Hatch, you " +"will call `hatch publish` to publish directly to PyPI instead of `hatch " +"publish -r test` which publishes to TestPyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:201 +msgid "" +"[Open up a web browser and go to the TestPyPI " +"website](https://test.pypi.org/)." +msgstr "" + +#: ../../tutorials/publish-pypi.md:202 +msgid "" +"[Create an account](https://test.pypi.org/account/register/) if you don't" +" already have one. Be sure to store your password in a safe place!" +msgstr "" + +#: ../../tutorials/publish-pypi.md:203 +msgid "Once you have an account setup, login to it." +msgstr "" + +#: ../../tutorials/publish-pypi.md:204 +msgid "" +"Search on [https://test.pypi.org/](https://test.pypi.org/) (and also on " +"[https://pypi.org/](https://pypi.org/)) to ensure that the package name " +"that you have selected doesn't already exist. If you are using our test " +"pyosPackage, then we suggest that you add your name or GitHub username to" +" the end of the package name to ensure it's unique." +msgstr "" + +#: ../../tutorials/publish-pypi.md:206 +msgid "Example: `pyosPackage_yourNameHere`." +msgstr "" + +#: ../../tutorials/publish-pypi.md +msgid "Renaming your project before publishing" +msgstr "" + +#: ../../tutorials/publish-pypi.md:211 +msgid "Required" +msgstr "" + +#: ../../tutorials/publish-pypi.md:213 +msgid "" +"Search your publishing location(s) to make sure your new name isn't taken" +" ([TestPyPI](https://test.pypi.org/), [PyPI](https://pypi.org/), [conda-" +"forge](https://conda-forge.org/packages/))" +msgstr "" + +#: ../../tutorials/publish-pypi.md:214 +msgid "" +"Update the project name in your pyproject.toml file (e.g. `name = " +"\"pyospackage_yourNameHere\"`)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:215 +msgid "" +"Update the module folder name to be the same (e.g. " +"`src/pyospackage_yourNameHere`)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:216 +msgid "Rebuild your project (`hatch build`)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:217 +msgid "Publish your package to capture the name (continue this tutorial!)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:219 +msgid "Recommended" +msgstr "" + +#: ../../tutorials/publish-pypi.md:221 +msgid "Update the Github repository name to align with the new package name" +msgstr "" + +#: ../../tutorials/publish-pypi.md:222 +msgid "" +"Update your local project folder to match the new package name (e.g. " +"`pyospackage_yourNameHere/src`)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:223 +msgid "Update mentions of your repository name in other files (e.g. `README.md`)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:227 +msgid "" +"This is a screenshot of the TestPyPI website. At the top in the search " +"bar, you can see the search for pyosPackage. The search return says there" +" were no results for pyosPackage Did you mean probpackage" +msgstr "" + +#: ../../tutorials/publish-pypi.md:229 +msgid "" +"Before you try to upload to TestPyPI, check to see if the name of your " +"package is already taken. You can do that using the search box at the top" +" of the TestPyPI website." +msgstr "" + +#: ../../tutorials/publish-pypi.md:233 +msgid "Setup 2-factor (2FA) authentication" +msgstr "" + +#: ../../tutorials/publish-pypi.md:235 +msgid "" +"2-factor authentication is a secure login process that allows you to use " +"a backup device that only you can access to validate that the person " +"logging in is really you. It addresses the issue of password phishing " +"where someone else gains access to a password and can login to your " +"account." +msgstr "" + +#: ../../tutorials/publish-pypi.md:238 +msgid "" +"This matters on PyPI because someone could login to your account and " +"upload a version of your package that has security issues. These issues " +"will then impact all of your users when they download and install that " +"version of the package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:240 +msgid "" +"2-factor authentication is required for PyPI authentication as of 1 " +"January 2024." +msgstr "" + +#: ../../tutorials/publish-pypi.md:244 +msgid "Step 4. Create a package upload token" +msgstr "" + +#: ../../tutorials/publish-pypi.md:246 +msgid "" +"To upload your package to TestPyPI (or PyPI), you will need to create a " +"token for your account first, and should then create a package-specific " +"token. (If you completed this step previously, you can reuse the tokens " +"when you upload your package again.)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:248 +msgid "Why create package-specific tokens?" +msgstr "" + +#: ../../tutorials/publish-pypi.md:250 +msgid "" +"It's ideal to create a package-specific token. When you create an " +"account-wide token this allows anyone with access to the account to then " +"access all of your TestPyPI (or PyPI) projects. By creating a package-" +"specific token, you are limiting the scope of the token to only your " +"specific package. This is just a safe way to set things up for you " +"particularly if you are collaborating with others on package development." +msgstr "" + +#: ../../tutorials/publish-pypi.md:253 +msgid "Follow the steps below to create your token." +msgstr "" + +#: ../../tutorials/publish-pypi.md:255 +msgid "Login to TestPyPI and go to your account settings" +msgstr "" + +#: ../../tutorials/publish-pypi.md:256 +msgid "Scroll down to the **API tokens** section" +msgstr "" + +#: ../../tutorials/publish-pypi.md:257 +msgid "Click on the **Add API Token** button" +msgstr "" + +#: ../../tutorials/publish-pypi.md:258 +msgid "" +"If you are new to using TestPyPI and don't have any packages there yet, " +"OR if you have other packages on TestPyPI but are uploading a new " +"package, you will need to create an account-wide token." +msgstr "" + +#: ../../tutorials/publish-pypi.md:259 +msgid "" +"When you create your token, be sure to copy the token value and store it " +"in a secure place before closing that browser." +msgstr "" + +#: ../../tutorials/publish-pypi.md:261 +msgid "Your token should look something like this:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:263 +msgid "`pypi-abunchofrandomcharactershere...`" +msgstr "" + +#: ../../tutorials/publish-pypi.md:265 +msgid "It should start with `pypi` followed by a dash and a bunch of characters." +msgstr "" + +#: ../../tutorials/publish-pypi.md:267 +msgid "Upload to TestPyPI using Hatch" +msgstr "" + +#: ../../tutorials/publish-pypi.md:269 +msgid "Once you have your token, you are ready to publish to TestPyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:272 +msgid "Run `hatch publish -r test`" +msgstr "" + +#: ../../tutorials/publish-pypi.md:274 +msgid "" +"`-r` stands for repository. In this case because you are publishing to " +"TestPyPI you will use `-r test`. Hatch will then ask for a username and " +"credentials." +msgstr "" + +#: ../../tutorials/publish-pypi.md:276 +msgid "" +"Add the word `__token__` for your username. This tells TestPyPI that you " +"are using a token value rather than a username." +msgstr "" + +#: ../../tutorials/publish-pypi.md:277 +msgid "Paste your TestPyPI token value in at the `Enter your credentials` prompt:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:288 +msgid "" +"If your credentials are valid, and you have already run `hatch build` and" +" thus have your 2 distribution files in a `dist/` directory then Hatch " +"will publish your package to TestPyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:292 +msgid "" +"Hatch also has a caching system so once you enter your credentials it " +"will remember them." +msgstr "" + +#: ../../tutorials/publish-pypi.md:295 +msgid "Install your package from TestPyPI" +msgstr "" + +#: ../../tutorials/publish-pypi.md:297 +msgid "" +"Once your package upload is complete, you can install it from TestPyPI. " +"You can find the installation instructions on the TestPyPI landing page " +"for your newly uploaded package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:302 +msgid "" +"A screenshot of the TestPyPI page for pyosPackage. It says pyosPackage " +"0.1.0 at the top with the pip install instructions below. The landing " +"page of the package has information from the package's README file." +msgstr "" + +#: ../../tutorials/publish-pypi.md:304 +msgid "" +"This is an example landing page for the pyosPackage that was just " +"uploaded. Notice at the top of the page there are instructions for how to" +" install the package from TestPyPI. You can simply copy that code and use" +" it to install your package from TestPyPI locally." +msgstr "" + +#: ../../tutorials/publish-pypi.md:307 +msgid "" +"As an example, [check out our pyOpenSci pyosPackage landing page on " +"TestPyPI](https://test.pypi.org/project/pyosPackage/). Notice that the " +"page has information about the current package version and also " +"installation instructions as follows:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:311 +msgid "`python -m pip install -i https://test.pypi.org/simple/ pyosPackage`" +msgstr "" + +#: ../../tutorials/publish-pypi.md:314 +msgid "" +"Publishing to TestPyPI vs PyPI While you can install from TestPyPI it's " +"not recommended that you publish to TestPyPI as a permanent way to " +"install your package. In fact, you cannot, because TestPyPI may delete " +"accounts after a time. TestPyPI is a perfect place to learn how to " +"publish your package and test the installation process. But your end goal" +" should be to publish to PyPI once you have figured out your workflow and" +" your package is ready to deploy." +msgstr "" + +#: ../../tutorials/publish-pypi.md:318 +msgid "Time to install your package" +msgstr "" + +#: ../../tutorials/publish-pypi.md:320 +msgid "" +"On your computer, activate the development environment that you wish to " +"install your newly published package in." +msgstr "" + +#: ../../tutorials/publish-pypi.md:322 +msgid "Run the installation instructions for your package from TestPyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md +msgid "Conda" +msgstr "" + +#: ../../tutorials/publish-pypi.md +msgid "venv Mac / Linux" +msgstr "" + +#: ../../tutorials/publish-pypi.md:346 +msgid "The value of end-to-end tools like hatch, flit and poetry" +msgstr "" + +#: ../../tutorials/publish-pypi.md:347 +msgid "" +"In this lesson you are using Hatch and hatchling to create, build and " +"publish your Python package. [Click here to learn about other packaging " +"tools in the ecosystem.](../package-structure-code/python-package-build-" +"tools.md)" +msgstr "" + +#: ../../tutorials/publish-pypi.md:351 +msgid "" +"teach them to setup trusted publisher for actions... in the actions " +"lesson https://pypi.org/help/#twofa" +msgstr "" + +#: ../../tutorials/publish-pypi.md:354 +msgid "" +"from PyPI: https://pypi.org/help/#apitoken - You can create a token for " +"an entire PyPI account, in which case, the token will work for all " +"projects associated with that account. Alternatively, you can limit a " +"token's scope to a specific project." +msgstr "" + +#: ../../tutorials/publish-pypi.md:357 +msgid "Package-specific token vs trusted publisher" +msgstr "" + +#: ../../tutorials/publish-pypi.md:359 +msgid "" +"For long run maintenance of your package, you have two options related to" +" PyPI publication." +msgstr "" + +#: ../../tutorials/publish-pypi.md:362 +msgid "" +"You can create a package-specific token which you will use to publish " +"your package (manually) to PyPI. This is a great option if you don't wish" +" to automate your PyPI publication workflow." +msgstr "" + +#: ../../tutorials/publish-pypi.md:363 +msgid "" +"You can also create an automated publication workflow on GitHub using " +"GitHub actions. This is a great way to make the publication process " +"easier and it also supports a growing maintainer team. In this case we " +"suggest you don't worry about the token and instead setup a specific " +"GitHub action that publishes your package when you make a release. You " +"can then create a \"trusted publisher\" workflow on PyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:365 +msgid "" +"You will learn how to create the automated trusted publisher workflow in " +"a followup lesson." +msgstr "" + +#: ../../tutorials/publish-pypi.md:368 +msgid "OPTIONAL: If you want to use a manual token-based publication workflow" +msgstr "" + +#: ../../tutorials/publish-pypi.md:370 +msgid "" +"If you plan to use your token regularly to publish to PyPI, we strongly " +"recommend going through the above steps again to create a token specific " +"to your new package." +msgstr "" + +#: ../../tutorials/publish-pypi.md:373 +msgid "To do this:" +msgstr "" + +#: ../../tutorials/publish-pypi.md:374 +msgid "Go to TestPyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:375 +msgid "Navigate to the \"Your Projects\" section of your account" +msgstr "" + +#: ../../tutorials/publish-pypi.md:376 +msgid "" +"Click on the manage button for the project that you wish to add a token " +"for" +msgstr "" + +#: ../../tutorials/publish-pypi.md:377 +msgid "Go to settings" +msgstr "" + +#: ../../tutorials/publish-pypi.md:378 +msgid "Click on \"Create a token for your-package-name-here\"" +msgstr "" + +#: ../../tutorials/publish-pypi.md:379 +msgid "" +"Create the token and follow the steps above publish your package using " +"the repository specific token." +msgstr "" + +#: ../../tutorials/publish-pypi.md:381 +msgid "And you're all done!" +msgstr "" + +#: ../../tutorials/publish-pypi.md:383 +msgid "You have published your package to TestPyPI!" +msgstr "" + +#: ../../tutorials/publish-pypi.md:385 +msgid "" +"Congratulations. You have now successfully published your package to " +"TestPyPI. If you have a package that is ready for real-world use on the " +"real PyPI, then you can follow the same steps (with the differences noted" +" above) to publish it on PyPI." +msgstr "" + +#: ../../tutorials/publish-pypi.md:387 +msgid "" +"Once you publish on PyPI, you can then easily add your package to the " +"conda-forge ecosystem using the [grayskull](https://conda-" +"forge.org/blog/posts/2020-03-05-grayskull/) tool." +msgstr "" + +#: ../../tutorials/publish-pypi.md:389 +msgid "You will learn how to do that in the next lesson." +msgstr "" + +#: ../../tutorials/publish-pypi.md:396 +msgid "https://docs.python.org/3/library/venv.html" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:1 +msgid "Make your Python package PyPI ready - pyproject.toml" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:3 +msgid "" +"In [the installable code lesson](installable-code), you learned how to " +"add the bare minimum information to a `pyproject.toml` file to make it " +"installable. You then learned how to [publish a bare minimum version of " +"your package to PyPI](publish-pypi.md)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:5 +msgid "Following that you learned how to add a:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:6 +msgid "[README.md](add-readme)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:7 +msgid "[LICENSE](add-license-coc) and" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:8 +msgid "[CODE_OF_CONDUCT](add-coc)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:10 +msgid "to the root of your project directory." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:12 +msgid "" +"To enhance the visibility of your package on PyPI and provide more " +"information about its compatibility with Python versions, project " +"development status, and project maintainers, you should add additional " +"metadata to your `pyproject.toml` file. This lesson will guide you " +"through the process." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:24 +msgid "" +"More about the `pyproject.toml` file and how it's used to store different" +" types of metadata about your package" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:25 +msgid "" +"How to declare information (metadata) about your project to help users " +"find and understand it on PyPI." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:27 +msgid "" +"If you wish to learn more about the `pyproject.toml` format, [check out " +"this page. ](../package-structure-code/pyproject-toml-python-package-" +"metadata.md)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md +msgid "Click for lesson takeaways" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:34 +msgid "When creating your pyproject.toml file, consider the following:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:36 +msgid "" +"There are only two required metadata tables that you need to install and " +"publish your Python package:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:37 +msgid "**[build-system]**" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:38 +msgid "**[project]**." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:39 +msgid "" +"The **[project]** table stores your package's metadata. Within the " +"**[project]** table, There are only two _required_ fields:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:40 +msgid "**name=**" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:41 +msgid "**version=**" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:42 +msgid "" +"You should add more metadata to the `[project]` table as it will make it " +"easier for users to find your project on PyPI. And it will also make it " +"easier for installers to understand how to install your package." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:43 +msgid "" +"When you are adding classifiers to the **[project]** table, only use " +"valid values from [PyPI’s classifier " +"page](https://PyPI.org/classifiers/). An invalid value here will raise an" +" error when you build and publish your package on PyPI." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:44 +msgid "" +"There is no specific order for tables in the `pyproject.toml` file. " +"However, fields need to be placed within the correct tables. For example " +"`requires =` always need to be in the **[build-system]** table." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:45 +msgid "" +"We suggest that you include your **[build-system]** table at the top of " +"your `pyproject.toml` file." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:50 +msgid "" +"The `pyproject.toml` file is a human and machine-readable file that " +"serves as the primary configuration file for your Python package." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:54 +msgid "" +"[Building your package](build-package) is the step that created the " +"distribution files that are required for you to publish to PyPI." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:58 +msgid "About the .toml format" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:60 +msgid "" +"The **pyproject.toml** file is written in [TOML (Tom's Obvious, Minimal " +"Language) format](https://toml.io/en/). TOML is an easy-to-read structure" +" that is based on key/value pairs. Each section in the **pyproject.toml**" +" file contains a `[table identifier]`. The TOML format can be compared to" +" other structured formats such as`.json`. However, the TOML format was " +"designed to be easier to read for humans." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:62 +msgid "" +"Below you can see the `[build-system]` table. Within that table there are" +" two required key/value pairs." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:65 +msgid "" +"`requires =` is the key and the value is `[\"hatchling\"]` within the " +"`[build-system]` array specified by square brackets `[]`." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:75 +msgid "What is the pyproject.toml used for?" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:77 +msgid "The pyproject.toml file tells your build tool:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:79 +msgid "" +"What build backend to use to build your package (we are using `hatchling`" +" in this tutorial but there are [many others to choose from](/package-" +"structure-code/python-package-build-tools))." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:80 +msgid "How and where to retrieve your package's version:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:81 +msgid "**statically** where you declare the version `version = \"0.1.0\"` or" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:82 +msgid "" +"**dynamically** where the tool looks to the most recent tag in your " +"history to determine the current version." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:83 +msgid "What dependencies your package needs" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:84 +msgid "What versions of Python your package supports (important for your users)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:86 +msgid "" +"The `pyproject.toml` file also makes it easy for anyone browsing your " +"GitHub repository to quickly understand your package's structure such as:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:89 +msgid "How your package is built," +msgstr "" + +#: ../../tutorials/pyproject-toml.md:90 +msgid "What Python versions and operating systems it supports" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:91 +msgid "What it does," +msgstr "" + +#: ../../tutorials/pyproject-toml.md:92 +msgid "Who maintains it" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:94 +msgid "" +"Finally, the pyproject.toml file is also often used to configure tools " +"such as static type checkers (e.g. mypy) and code formatters/linters " +"(e.g. black, ruff)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:97 +msgid "" +"Check out the [PyPA " +"documentation](https://packaging.python.org/en/latest/tutorials" +"/packaging-projects/#choosing-a-build-backend) if you are interested in " +"setting build configurations for other tools." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:99 +msgid "" +"Note that some build tools may deviate in how they store project " +"metadata. As such you may want to refer to their documentation if you " +"decide to use a tool other than Hatch and hatchling. We have selected " +"hatchling and hatch as our tool of choice for this tutorial as it adheres" +" to PyPA rules and guidelines." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:103 +msgid "How is pyproject.toml metadata used?" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:105 +msgid "" +"The pyproject.toml file is the file that your build tool uses to populate" +" a `METADATA` that is included in your Python distribution files that get" +" published to PyPI. This `METADATA` file is then used by PyPI to populate" +" your package's PyPI landing page and help users filter through the tens " +"of thousands of packages published there." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:108 +msgid "" +"Image showing the left side bar of PyPI for the package xclim. The " +"section at the top says Classifier. Below there is a list of items " +"including Development status, intended audience, License, natural " +"language, operating system, programming language and topic. Below each of" +" those sections are various classifier options.\" width=\"300px\">" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:113 +msgid "" +"When you add the classifier section to your pyproject.toml and your " +"package is built, the build tool organizes the metadata into a format " +"that PyPI can understand and represent on your PyPI landing page. These " +"classifiers also allow users to sort through packages by version of " +"python they support, categories and more." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:119 +msgid "A more in-depth overview of pyproject.toml files" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:121 +msgid "" +"[Our guidebook page has a more in depth overview of this file" +"](../package-structure-code/pyproject-toml-python-package-metadata/)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:124 +msgid "How to update your pyproject.toml file" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:126 +msgid "" +"In the last lesson, you created a bare-bones pyproject.toml file that " +"contained the core elements needed to build your package:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:130 +msgid "" +"A `[build-system]` table where you defined your project's backend build " +"tool (`hatchling`)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:131 +msgid "A `[project]` table where you defined your project's version and name." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:133 +msgid "The `pyproject.toml` file that you created, looked like this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:145 +msgid "" +"Your next step is to add additional recommended metadata fields that will" +" both help users find your package on PyPI and also better describe the " +"scope of your package. Once you add this metadata, you don't have to do " +"it again. These metadata fields will only be updated periodically when " +"you do something such as:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:148 +msgid "drop a package dependency" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:149 +msgid "modify what Python versions your package supports." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:151 +msgid "More on hatchling" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:154 +msgid "" +"The documentation for the hatchling back-end is " +"[here](https://hatch.pypa.io/latest/config/metadata/)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:157 +msgid "Step 1: Add Author, maintainer and project description" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:159 +msgid "" +"After completing the [installable code tutorial](installable-code), you " +"should have a pyproject.toml file with a project name and a version in " +"the `[project]` table." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:167 +msgid "Add the following to your table:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:169 +msgid "" +"A **description** of your package. This should be a single line and " +"should briefly describe the goal of your package using non technical " +"terms if as all possible!" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:170 +msgid "package **authors**" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:171 +msgid "package **maintainers**" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:173 +msgid "The `description` is just a string like the other values you've set:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:184 +msgid "" +"When you add authors and maintainers you need to use a format that will " +"look like a Python list with a dictionary within it:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:198 +msgid "Author names & emails" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:202 +msgid "" +"There is a quirk with PyPI for authors that have names but not emails in " +"the pyproject.toml. If you are missing the email for one or more authors " +"or maintainers, like this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:211 +msgid "" +"Then we suggest that you only provide names in your list of names to " +"ensure that everything renders properly on your PyPI page - like this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:220 +msgid "don't have emails for everyone, we suggest that you only add names." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:223 +msgid "" +"Your `pyproject.toml` file now should look like the example below. It is " +"OK if you only have 1 author and the same author is also maintainer of " +"your package:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md +msgid "" +"Learn More: What's the difference between author and maintainer in open " +"source?" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:251 +msgid "" +"When adding maintainers and authors, you may want to think about the " +"difference between the two." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:253 +msgid "Authors generally include people who:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:254 +msgid "originally created / designed developed the package and" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:255 +msgid "people who add new functionality to the package." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:257 +msgid "" +"Whereas maintainers are the people that are currently, actively working " +"on the project. It is often the case that there is overlap in authors and" +" maintainers. As such these lists may be similar or the same." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:259 +msgid "" +"A good example of when the lists might diverge is sometimes you have a " +"package where an initial author developed it and then stepped down as a " +"maintainer to move on to other things. This person may continue to be " +"considered an author but no longer actively maintains the package." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:261 +msgid "" +"It is important to note that there are many ways to define author vs " +"maintainer and we don't prescribe a single approach in this tutorial." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:263 +msgid "" +"However, we encourage you to consider carefully, for PyPI publication, " +"who you want to have listed as authors and maintainers on your PyPI " +"landing page." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:267 +msgid "Step 2: Add README and license" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:269 +msgid "" +"In the previous lessons, you added both a [README.md](add-readme) file " +"and a [LICENSE](add-license-coc) to your package repository. Once you " +"have those files, you can add them to your pyproject.toml file as links " +"following the example below." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:297 +msgid "Step 3: Specify Python version with `requires-python`" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:299 +msgid "" +"Add the `requires-python` field to your `pyproject.toml` `[project]` " +"table. The `requires-python` field helps pip identify which Python " +"versions that your package supports. It is set to a single value. The " +"[packaging " +"specification](https://packaging.python.org/en/latest/specifications" +"/core-metadata/#core-metadata-requires-python) defines`requires-python` " +"as a string that uses version specifiers. Most projects will specify the " +"oldest Python version supported by the package. In some advanced cases, " +"an upper bound is set to indicate which future Python versions, if any, " +"will be supported." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:331 +msgid "Step 4: Specify Dependencies" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:333 +msgid "" +"Next add your dependencies table to the project table. The `dependencies " +"=` section contains a list (or array in the toml language) of the Python " +"packages that your package requires to run properly in a Python " +"environment. Similar to the requirements listed in the `[build-system]` " +"table above:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:341 +msgid "dependencies are added in an array (similar to a Python list) structure." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:347 +msgid "" +"A dependency can be limited to specific versions using a **version " +"specifier.** If the dependency has no version specifier after the " +"dependency name, your package can use any version of the dependent " +"package. Code changes over time, bugs are fixed, APIs change, and so it's" +" good to be clear about which version of the dependency you wrote your " +"code to be compatible with - a package you wrote this year probably isn't" +" compatible with numpy v0.0.1!" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:351 +msgid "" +"[Learn more about various ways to specify ranges of package versions " +"here.](https://packaging.python.org/en/latest/specifications/version-" +"specifiers/#id5)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:353 +msgid "" +"The most common version specifier is a **lower bound,** allowing any " +"version higher than the specified version. Ideally you should set this to" +" the lowest version that is still compatible with your package, but in " +"practice for new packages this is often set at the version that was " +"current at the time the package was written[^lowerbound]." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:358 +msgid "Lower bounds look like this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:364 +msgid "" +"Commas are used to separate individual dependencies, and each package in " +"your `dependencies` section can use different types of version " +"specifiers:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:375 +msgid "Your `pyproject.toml` file will now look like this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:405 +msgid "Pin dependencies with caution" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:406 +msgid "" +"\"Pinning\" a dependency means setting it to a specific version, like " +"this:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:408 +msgid "`numpy == 1.0`." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:410 +msgid "" +"If you are building a library package that other developers will depend " +"upon, you must be cautious before pinning to a precise dependency " +"version. Applications, such as production websites, will often pin their " +"dependencies since other packages will not depend on their project. This " +"is because users will be installing your package into various " +"environments. A dependency pinned to a single specific version can make " +"resolving a Python environment more challenging. As such only pin " +"dependencies to a specific version if you absolutely need to do so." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:418 +msgid "" +"Similarly, you should be cautious when specifying an upper bound on a " +"package. These two specifications are equivalent:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:426 +msgid "" +"One build tool that you should be aware of that pins dependencies to an " +"upper bound by default is Poetry. [Read more about how to safely add " +"dependencies with Poetry, here.](challenges-with-poetry)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:429 +msgid "Step 5: Add PyPI classifiers" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:431 +msgid "" +"Next you will add classifiers to your `pyproject.toml` file. The value " +"for each classifier that you add to your `pyproject.toml` file must come " +"from the list of [PyPI accepted classifier values found " +"here](https://PyPI.org/classifiers/). Any deviations in spelling and " +"format will cause issues when you publish to PyPI." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:433 +msgid "What happens when you use incorrect classifiers?" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:436 +msgid "" +"If you do not [use standard classifier " +"values](https://PyPI.org/classifiers/), when you try to publish your " +"package on PyPI it will be rejected. 😔 Don't worry if PyPI rejects you on" +" your first try! It has happened to all of us." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:439 +msgid "Review that list and add items below to your `pyproject.toml` file:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:441 +msgid "development status" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:442 +msgid "intended audiences" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:443 +msgid "topic" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:444 +msgid "license and" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:445 +msgid "programming language support" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:447 +msgid "" +"The classifier key should look something like the example below. A few " +"notes:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:449 +msgid "" +"Your classifier values might be different depending upon the license you " +"have selected for your package, your intended audience, development " +"status of your package and the Python versions that you support" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:450 +msgid "" +"You can add as many classifiers as you wish as long as you use the " +"[designated PyPI classifier values](https://PyPI.org/classifiers/)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:490 +msgid "" +"Note that while classifiers are not required in your `pyproject.toml` " +"file, they will help users find your package. As such we strongly " +"recommend that you add them." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:492 +msgid "Step 6: Add the `[project.urls]` table" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:494 +msgid "Finally, add the project.urls table to your pyproject.toml file." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:496 +msgid "" +"`project.urls` contains links that are relevant for your project. You " +"might want to include:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:498 +msgid "" +"**Homepage:** A link to your published documentation for your project. If" +" you are working through this tutorial, then you may not have this link " +"yet. That's ok, you can skip it for the time being." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:499 +msgid "" +"**Bug reports:** a link to your issues / discussions or wherever you want" +" users to report bugs." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:500 +msgid "**Source:** the GitHub / GitLab link for your project." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:546 +msgid "" +"There are many other urls that you can add here. Check out the [README " +"file here for an overview](https://github.com/patrick91/links-demo)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:549 +msgid "Putting it all together - your completed pyproject.toml file" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:551 +msgid "" +"Below is an example of a complete `pyproject.toml` file that is commented" +" with all of the sections we discussed above." +msgstr "" + +#: ../../tutorials/pyproject-toml.md +msgid "Appendix - Click for a fully commented pyproject.toml file" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:601 +msgid "" +"Below is a fully commented pyproject.toml file if you want to use it for " +"reference." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:666 +msgid "Example `pyproject.toml` files" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:668 +msgid "" +"Below are some examples of `pyproject.toml` files from various packages " +"in the scientific and pyOpenSci ecosystem." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:669 +msgid "" +"[PyPA's fully documented example pyproject.toml " +"file](https://github.com/pypa/sampleproject/blob/main/pyproject.toml)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:670 +msgid "" +"[taxpasta has a nicely organized pyproject.toml file and is a pyOpenSci " +"approved " +"package](https://github.com/taxprofiler/taxpasta/blob/f9f6eea2ae7dd08bb60a53dd49ad77e4cf143573/pyproject.toml)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:676 +msgid "At this point you've created:" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:678 +msgid "A [README.md](add-readme) file for your package" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:679 +msgid "A [CODE_OF_CONDUCT.md](add-coc) file to support your user community" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:680 +msgid "" +"And a [LICENSE](add-license-coc) file which provides legal boundaries " +"around how people can and can't use your software" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:682 +msgid "" +"You also learned [how to publish your package to (test)PyPI](publish-" +"pypi)." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:684 +msgid "Publish a new version of your package to PyPI" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:686 +msgid "" +"You are now ready to publish a new version of your Python package to " +"(test) PyPI. When you do this you will see that the landing page for your" +" package now contains a lot more information." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:688 +msgid "Try to republish now." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:690 +msgid "" +"First, update the version of your package in your pyproject toml file. " +"Below version is updated from `0.1` to `0.1.1`." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:703 +msgid "Now use hatch to publish the new version of your package to test.PyPI.org." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:710 +msgid "Next (optional) step - publishing to conda-forge" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:712 +msgid "" +"You now have all of the skills that you need to publish your package to " +"PyPI." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:715 +msgid "" +"If you also want to publish your package on conda-forge (which is a " +"channel within the conda ecosystem), you will learn how to do that in the" +" next lesson." +msgstr "" + +#: ../../tutorials/pyproject-toml.md:719 +msgid "" +"Really good resources from jeremiah " +"https://daniel.feldroy.com/posts/2023-08-pypi-project-urls-cheatsheet " +"useful (and the linked links-demo even more so)" +msgstr "" + +#: ../../tutorials/pyproject-toml.md:356 +msgid "" +"Some packaging tools will do this for you when you add a dependency using" +" their cli interface. For example [`poetry add`](https://python-" +"poetry.org/docs/cli/#add) will add the most recent version with a `^` " +"specifier, and [`pdm add`](https://pdm-" +"project.org/latest/reference/cli/#add) will add the most recent version " +"with `>=`." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:1 +msgid "Using Hatch to Migrate setup.py to a pyproject.toml" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:3 +msgid "" +"Hatch can be particularly useful to generate your project's " +"`pyproject.toml` if your project already has a `setup.py`." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:5 +msgid "Note" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:8 +msgid "" +"This step is not necessary and is only useful if your project already has" +" a `setup.py` file defined." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:9 +msgid "" +"If your project does not already define a `setup.py` see [Make your " +"Python code installable](installable-code.md)" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:17 +msgid "" +"The process of using Hatch to transition to using `pyproject.toml` for " +"projects that already have a `setup.py` defined." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:20 +msgid "What is Hatch?" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:22 +msgid "" +"Hatch is a Python package manager designed to streamline the process of " +"creating, managing, and distributing Python packages. It provides a " +"convenient CLI (Command-Line Interface) for tasks such as creating new " +"projects, managing dependencies, building distributions, and publishing " +"packages to repositories like PyPI." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:28 +msgid "See [Get to know Hatch](get-to-know-hatch.md) for more information." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:31 +msgid "Prerequisites" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:33 +msgid "" +"Before we begin, ensure that you have Hatch installed on your system. You" +" can install it via pip:" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:39 +msgid "Sample Directory Tree" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:41 +msgid "" +"Let's take a look at a sample directory tree structure before and after " +"using `hatch init`:" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:43 +msgid "Before `hatch init`" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:59 +msgid "After `hatch init`" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:77 +msgid "" +"As you can see, the main change after running `hatch init` is the " +"addition of the `pyproject.toml` file in the project directory." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:79 +msgid "Step-by-Step Guide" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:81 +msgid "" +"Now, let's walk through the steps to use Hatch to create a " +"`pyproject.toml` file for your project." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:83 +msgid "" +"**Navigate to Your Project Directory**: Open your terminal or command " +"prompt and navigate to the directory where your Python project is " +"located." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:85 +msgid "" +"**Initialize Hatch**: Run the following command to initialize Hatch in " +"your project directory:" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:91 +msgid "" +"**Review and Customize**: After running the previous command, Hatch will " +"automatically generate a `pyproject.toml` file based on your existing " +"project configuration. Take some time to review the contents of the " +"generated `pyproject.toml` file. You may want to customize certain " +"settings or dependencies based on your project's requirements (see " +"[pyproject.toml tutorial](pyproject-toml.md) for more information about " +"the `pyproject.toml`)." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:93 +msgid "" +"**Verify**: Verify that the `pyproject.toml` file accurately reflects " +"your project configuration and dependencies. You can manually edit the " +"file if needed, but be cautious and ensure that the syntax is correct." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:95 +msgid "" +"**Delete setup.py**: Since we're migrating to using `pyproject.toml` " +"exclusively, the `setup.py` file becomes unnecessary. You can safely " +"delete it from your project directory." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:97 +msgid "" +"**Test Build**: Before proceeding further, it's essential to ensure that " +"your project builds successfully using only the `pyproject.toml` file. " +"Run the following command to build your project:" +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:103 +msgid "" +"This command will build your project based on the specifications in the " +"`pyproject.toml` file. Make sure to check for any errors or warnings " +"during the build process." +msgstr "" + +#: ../../tutorials/setup-py-to-pyproject-toml.md:105 +msgid "" +"**Test Existing Functionality**: After successfully building your project" +" with `pyproject.toml`, it's crucial to ensure that your project's " +"existing functionality remains intact. Run any pre-existing tests to " +"verify that everything still works as expected." +msgstr ""