From bcdb31abc17957425c486688a198c50df1d3fa04 Mon Sep 17 00:00:00 2001 From: Tetsuo Koyama Date: Fri, 2 Aug 2024 18:05:34 +0900 Subject: [PATCH 1/8] Create empty translation files for Japanese --- locales/es/LC_MESSAGES/CONTRIBUTING.po | 147 +- locales/es/LC_MESSAGES/tutorials.po | 321 +- locales/ja/LC_MESSAGES/CONTRIBUTING.po | 436 ++ locales/ja/LC_MESSAGES/TRANSLATING.po | 718 +++ locales/ja/LC_MESSAGES/documentation.po | 2546 ++++++++ locales/ja/LC_MESSAGES/index.po | 484 ++ .../ja/LC_MESSAGES/package-structure-code.po | 5302 ++++++++++++++++ locales/ja/LC_MESSAGES/tests.po | 1003 +++ locales/ja/LC_MESSAGES/tutorials.po | 5537 +++++++++++++++++ noxfile.py | 2 +- 10 files changed, 16375 insertions(+), 121 deletions(-) create mode 100644 locales/ja/LC_MESSAGES/CONTRIBUTING.po create mode 100644 locales/ja/LC_MESSAGES/TRANSLATING.po create mode 100644 locales/ja/LC_MESSAGES/documentation.po create mode 100644 locales/ja/LC_MESSAGES/index.po create mode 100644 locales/ja/LC_MESSAGES/package-structure-code.po create mode 100644 locales/ja/LC_MESSAGES/tests.po create mode 100644 locales/ja/LC_MESSAGES/tutorials.po diff --git a/locales/es/LC_MESSAGES/CONTRIBUTING.po b/locales/es/LC_MESSAGES/CONTRIBUTING.po index b2a801f4..0cddd183 100644 --- a/locales/es/LC_MESSAGES/CONTRIBUTING.po +++ b/locales/es/LC_MESSAGES/CONTRIBUTING.po @@ -9,7 +9,7 @@ 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" +"POT-Creation-Date: 2024-08-02 18:04+0900\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: es\n" @@ -119,96 +119,117 @@ 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." +"Python Packaging Guide repository into your personal GitHub space. To " +"\"fork\" a repository in GitHub means to create a copy of the main " +"repository, or repo, that you have complete control over and can modify " +"as you see fit." msgstr "" #: ../../CONTRIBUTING.md:37 -msgid "" -"*__TODO__: This section should show a beginner user how to fork a " -"repository in GitHub.*" +msgid "To fork a repo," msgstr "" #: ../../CONTRIBUTING.md:39 -msgid "Contributing via the GitHub website" +msgid "Make sure you are logged into GitHub." msgstr "" #: ../../CONTRIBUTING.md:41 -msgid "How to edit a MarkDown file" +msgid "" +"Go to the repo you would like to fork, in this case the [Python Packaging" +" Guide](https://www.github.com/pyopensci/python-package-guide) repo." msgstr "" #: ../../CONTRIBUTING.md:43 msgid "" +"In the top right-hand corner of the page there is a 'Fork' button. Click " +"that button. You will be brought to a new page where you will 'Create a " +"new fork'. Feel free to keep all the default inputs and click 'Create " +"fork'. This will create a copy of the repo at " +"`https://github.com//python-package-guide`, where `` " +"is your GitHub username." +msgstr "" + +#: ../../CONTRIBUTING.md:47 +msgid "Contributing via the GitHub website" +msgstr "" + +#: ../../CONTRIBUTING.md:49 +msgid "How to edit a MarkDown file" +msgstr "" + +#: ../../CONTRIBUTING.md:51 +msgid "" "*__TODO__: This section should show how to use the GitHub interface to " "edit and previewing a Markdown file.*" msgstr "" -#: ../../CONTRIBUTING.md:45 +#: ../../CONTRIBUTING.md:53 msgid "How to commit your changes" msgstr "" -#: ../../CONTRIBUTING.md:47 +#: ../../CONTRIBUTING.md:55 msgid "" "*__TODO__: This section should show how to commit changes via the GitHub " "interface.*" msgstr "" -#: ../../CONTRIBUTING.md:49 +#: ../../CONTRIBUTING.md:57 msgid "Contributing locally on your computer" msgstr "" -#: ../../CONTRIBUTING.md:51 +#: ../../CONTRIBUTING.md:59 msgid "Clone your forked repository" msgstr "" -#: ../../CONTRIBUTING.md:53 +#: ../../CONTRIBUTING.md:61 msgid "" "*__TODO__: This section should show how to clone a repository from GitHub" " into your computer.*" msgstr "" -#: ../../CONTRIBUTING.md:55 +#: ../../CONTRIBUTING.md:63 msgid "Create a new branch" msgstr "" -#: ../../CONTRIBUTING.md:57 +#: ../../CONTRIBUTING.md:65 msgid "*__TODO__: This section should show how to create a new branch.*" msgstr "" -#: ../../CONTRIBUTING.md:59 +#: ../../CONTRIBUTING.md:67 msgid "Create a virtual environment" msgstr "" -#: ../../CONTRIBUTING.md:61 +#: ../../CONTRIBUTING.md:69 msgid "" "*__TODO__: This section should show how to create a virtual environment " "using venv.*" msgstr "" -#: ../../CONTRIBUTING.md:63 +#: ../../CONTRIBUTING.md:71 msgid "Install the development dependencies" msgstr "" -#: ../../CONTRIBUTING.md:65 +#: ../../CONTRIBUTING.md:73 msgid "" "*__TODO__: This section should show how to install the development " "dependencies defined in pyproject.toml.*" msgstr "" -#: ../../CONTRIBUTING.md:67 +#: ../../CONTRIBUTING.md:75 msgid "Commit your changes" msgstr "" -#: ../../CONTRIBUTING.md:69 +#: ../../CONTRIBUTING.md:77 msgid "" "*__TODO__: This section should describe how to commit from the command " "line.*" msgstr "" -#: ../../CONTRIBUTING.md:71 +#: ../../CONTRIBUTING.md:79 msgid "How to build the guide locally" msgstr "" -#: ../../CONTRIBUTING.md:73 +#: ../../CONTRIBUTING.md:81 msgid "" "*__TODO__: This section should describe the different sessions in nox " "related to building the docs: docs, docs-test, docs-live. It should also " @@ -216,85 +237,85 @@ msgid "" " browser or using the live version from docs-live*" msgstr "" -#: ../../CONTRIBUTING.md:75 +#: ../../CONTRIBUTING.md:83 msgid "Before you submit your pull request" msgstr "" -#: ../../CONTRIBUTING.md:77 +#: ../../CONTRIBUTING.md:85 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 +#: ../../CONTRIBUTING.md:87 msgid "Submitting a pull request with your contribution" msgstr "" -#: ../../CONTRIBUTING.md:81 +#: ../../CONTRIBUTING.md:89 msgid "How to make a pull request" msgstr "" -#: ../../CONTRIBUTING.md:83 +#: ../../CONTRIBUTING.md:91 msgid "" "*__TODO__: This section should describe how to make a pull request in " "GitHub.*" msgstr "" -#: ../../CONTRIBUTING.md:85 +#: ../../CONTRIBUTING.md:93 msgid "What happens when you submit a pull request (CI/CD)" msgstr "" -#: ../../CONTRIBUTING.md:87 +#: ../../CONTRIBUTING.md:95 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 +#: ../../CONTRIBUTING.md:97 msgid "What to expect from the review process" msgstr "" -#: ../../CONTRIBUTING.md:91 +#: ../../CONTRIBUTING.md:99 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 +#: ../../CONTRIBUTING.md:101 msgid "Additional help" msgstr "" -#: ../../CONTRIBUTING.md:95 +#: ../../CONTRIBUTING.md:103 msgid "How to get help" msgstr "" -#: ../../CONTRIBUTING.md:97 +#: ../../CONTRIBUTING.md:105 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 +#: ../../CONTRIBUTING.md:107 msgid "Additional resources" msgstr "" -#: ../../CONTRIBUTING.md:101 +#: ../../CONTRIBUTING.md:109 msgid "" "*__TODO__: It should also include links to beginner documentation, like " "the GitHub docs.*" msgstr "" -#: ../../CONTRIBUTING.md:103 +#: ../../CONTRIBUTING.md:111 msgid "Annex" msgstr "" -#: ../../CONTRIBUTING.md:105 +#: ../../CONTRIBUTING.md:113 msgid "Code examples" msgstr "" -#: ../../CONTRIBUTING.md:107 +#: ../../CONTRIBUTING.md:115 msgid "" "This guide uses the [literalinclude Sphinx directive](https://www.sphinx-" "doc.org/en/master/usage/restructuredtext/directives.html#directive-" @@ -302,18 +323,18 @@ msgid "" "for use in the documentation is kept in the `examples/` folder." msgstr "" -#: ../../CONTRIBUTING.md:111 +#: ../../CONTRIBUTING.md:119 msgid "Referencing code in documentation" msgstr "" -#: ../../CONTRIBUTING.md:113 +#: ../../CONTRIBUTING.md:121 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 +#: ../../CONTRIBUTING.md:124 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 " @@ -323,7 +344,7 @@ msgid "" "the later can protect your example from future modifications to the code." msgstr "" -#: ../../CONTRIBUTING.md:121 +#: ../../CONTRIBUTING.md:129 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" @@ -331,17 +352,17 @@ msgid "" "way to keep the same documentation content even through code refactors." msgstr "" -#: ../../CONTRIBUTING.md:125 +#: ../../CONTRIBUTING.md:133 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 +#: ../../CONTRIBUTING.md:136 msgid "Creating code for documentation" msgstr "" -#: ../../CONTRIBUTING.md:130 +#: ../../CONTRIBUTING.md:138 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) " @@ -350,7 +371,7 @@ msgid "" "code-in-documentation)." msgstr "" -#: ../../CONTRIBUTING.md:134 +#: ../../CONTRIBUTING.md:142 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 " @@ -359,7 +380,7 @@ msgid "" "create a new folder in the `examples` directory." msgstr "" -#: ../../CONTRIBUTING.md:138 +#: ../../CONTRIBUTING.md:146 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 " @@ -368,14 +389,14 @@ msgid "" "file, new methods after all existing ones in a class." msgstr "" -#: ../../CONTRIBUTING.md:142 +#: ../../CONTRIBUTING.md:150 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 +#: ../../CONTRIBUTING.md:153 msgid "" "***⚠️ WARNING***: great care should be taken when modifying existing " "example code, especially any modification beyond appending to the end of " @@ -386,29 +407,43 @@ msgid "" "and then checking those pages in a new build." msgstr "" -#: ../../CONTRIBUTING.md:153 +#: ../../CONTRIBUTING.md:161 msgid "Example:" msgstr "" -#: ../../CONTRIBUTING.md:155 +#: ../../CONTRIBUTING.md:163 msgid "Instead of writing example code in markdown like this" msgstr "" -#: ../../CONTRIBUTING.md:166 +#: ../../CONTRIBUTING.md:174 msgid "The python can be extracted into a `.py` file" msgstr "" -#: ../../CONTRIBUTING.md:180 +#: ../../CONTRIBUTING.md:188 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 +#: ../../CONTRIBUTING.md:191 msgid "Instead of writing this" msgstr "" -#: ../../CONTRIBUTING.md:195 +#: ../../CONTRIBUTING.md:203 msgid "an example could be extracted from an existing toml file" msgstr "" + +#~ msgid "" +#~ "Independently of the approach you " +#~ "choose, the first step is to fork" +#~ " the Python Packaging Guide repository " +#~ "into your personal GitHub space." +#~ msgstr "" + +#~ msgid "" +#~ "*__TODO__: This section should show a" +#~ " beginner user how to fork a " +#~ "repository in GitHub.*" +#~ msgstr "" + diff --git a/locales/es/LC_MESSAGES/tutorials.po b/locales/es/LC_MESSAGES/tutorials.po index 3427e46d..137d86ab 100644 --- a/locales/es/LC_MESSAGES/tutorials.po +++ b/locales/es/LC_MESSAGES/tutorials.po @@ -9,7 +9,7 @@ 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" +"POT-Creation-Date: 2024-08-02 18:04+0900\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: es\n" @@ -913,116 +913,231 @@ msgstr "" 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" +#: ../../tutorials/get-to-know-hatch.md:1 +msgid "Get to Know Hatch" msgstr "" #: ../../tutorials/get-to-know-hatch.md:3 msgid "" -"Our Python packaging tutorials use the tool Hatch. In this tutorial, you " -"will install and get to know Hatch a bit more before starting to use it." +"Our Python packaging tutorials use the tool " +"[Hatch](https://hatch.pypa.io/latest/). While there are [many great " +"packaging tools](/package-structure-code/python-package-build-tools) out " +"there, we have selected Hatch because:" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:6 -msgid "Install Hatch" +#: ../../tutorials/get-to-know-hatch.md:8 +msgid "" +"It is an end-to-end tool that supports most of the steps required to " +"create a quality Python package. Beginners will have fewer tools to learn" +" if they use Hatch." msgstr "" -#: ../../tutorials/get-to-know-hatch.md:7 +#: ../../tutorials/get-to-know-hatch.md:11 msgid "" -"To begin, install Hatch from the command line using " -"[pipx](https://pipx.pypa.io/stable/)" +"It supports different build back-ends if you ever need to compile code in" +" other languages." msgstr "" -#: ../../tutorials/get-to-know-hatch.md:14 +#: ../../tutorials/get-to-know-hatch.md:13 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." +"As a community, pyOpenSci has decided that Hatch is a user-friendly tool " +"that supports many different scientific Python use cases." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:16 +msgid "" +"In this tutorial, you will install and get to know Hatch a bit more " +"before starting to use it." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:19 +msgid "You need two things to successfully complete this tutorial:" msgstr "" #: ../../tutorials/get-to-know-hatch.md:21 +msgid "You need Python installed." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:22 +msgid "You need Hatch installed." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:25 +msgid "" +"If you don't already have Python installed on your computer, Hatch will " +"do it for you when you install Hatch." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:29 +msgid "Install Hatch" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:31 +msgid "" +"To begin, follow the operating-system-specific instructions below to " +"install Hatch." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md +msgid "MAC" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:38 +msgid "" +"Follow the instructions " +"[here](https://hatch.pypa.io/latest/install/#installers)." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:40 +msgid "" +"Download the latest GUI installer for MAC [hatch-" +"universal.pkg](https://github.com/pypa/hatch/releases/latest/download" +"/hatch-universal.pkg)." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:41 +msgid "Run the installer and follow the setup instructions." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:42 +msgid "If your terminal is open, then restart it." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md +msgid "Windows" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:48 +msgid "" +"In your browser, download the correct `.msi` file for your system: " +"[hatch-x64.msi](https://github.com/pypa/hatch/releases/latest/download/hatch-x64.msi)" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:50 +msgid "Run your downloaded installer file and follow the on-screen instructions." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md +msgid "Linux" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:56 +msgid "" +"We suggest that you install Hatch using pipx on Linux. however, if you " +"prefer another method, check out the [Hatch installation " +"documentation](https://hatch.pypa.io/latest/install/) for other methods." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:70 +msgid "" +"Hatch can also be installed directly using " +"[pip](https://hatch.pypa.io/latest/install/#pip) or " +"[conda](https://hatch.pypa.io/latest/install/#conda). We encourage you to" +" follow the instructions above because we have found that the Hatch " +"installers for Windows and Mac are the easiest and most efficient." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:74 +msgid "" +"Our Linux users have found success installing Hatch with pipx if they " +"already use apt install." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:77 msgid "" -"You can check that hatch is working properly by issuing a simple command " -"to get the version" +"Both approaches (using a graphical installer on Windows/Mac and pipx) " +"ensure that you have Hatch installed globally. A global install means " +"that Hatch is available across all of your Python environments on your " +"computer." msgstr "" -#: ../../tutorials/get-to-know-hatch.md:28 -msgid "Note the version numbers will likely be different" +#: ../../tutorials/get-to-know-hatch.md:82 +msgid "Check that hatch installed correctly" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:30 -msgid "Configure hatch" +#: ../../tutorials/get-to-know-hatch.md:84 +msgid "" +"Once you have completed the installation instructions above, you can open" +" your terminal, and make sure that Hatch installed correctly using the " +"command below:" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:32 +#: ../../tutorials/get-to-know-hatch.md:92 msgid "" -"Once you have installed Hatch, you will want to customize the " -"configuration." +"*Note the version number output of `hatch --version` will likely be " +"different from the output above in this tutorial.*" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:95 +msgid "Configure Hatch" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:34 +#: ../../tutorials/get-to-know-hatch.md:97 msgid "" -"Hatch stores your configuration information in a [`config.toml` " +"Once you have installed Hatch, you can customize its configuration. This " +"includes setting the default name and setup for every package you create." +" While this step is not required, we suggest that you do it." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:101 +msgid "" +"Hatch stores your configuration in a [`config.toml` " "file](https://hatch.pypa.io/latest/config/project-templates/)." msgstr "" -#: ../../tutorials/get-to-know-hatch.md:36 +#: ../../tutorials/get-to-know-hatch.md:103 msgid "" "While you can update the `config.toml` file through the command line, it " -"might be easier to look at it and update it in a text editor if you are " +"might be easier to look at and update it in a text editor if you are " "using it for the first time." msgstr "" -#: ../../tutorials/get-to-know-hatch.md:39 -msgid "Step 1: Open and edit your `config.toml` file" +#: ../../tutorials/get-to-know-hatch.md:107 +msgid "Step 1: Open and Edit Your `config.toml` File" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:41 +#: ../../tutorials/get-to-know-hatch.md:109 msgid "" "To open the config file in your file browser, run the following command " "in your shell:" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:43 +#: ../../tutorials/get-to-know-hatch.md:112 msgid "`hatch config explore`" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:45 +#: ../../tutorials/get-to-know-hatch.md:114 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." +"This will open up a directory window that allows you to double-click on " +"the file and open it in your favorite text editor." msgstr "" -#: ../../tutorials/get-to-know-hatch.md:47 +#: ../../tutorials/get-to-know-hatch.md:117 msgid "" "You can also retrieve the location of the Hatch config file by running " "the following command in your shell:" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:54 +#: ../../tutorials/get-to-know-hatch.md:125 msgid "Step 2 - update your email and name" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:56 +#: ../../tutorials/get-to-know-hatch.md:127 msgid "" "Once the file is open, update the [template] table of the `config.toml` " "file with your name and email. This information will be used in any " "`pyproject.toml` metadata files that you create using Hatch." msgstr "" -#: ../../tutorials/get-to-know-hatch.md:64 +#: ../../tutorials/get-to-know-hatch.md:137 msgid "Step 3" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:66 +#: ../../tutorials/get-to-know-hatch.md:139 msgid "Next, set tests to false in the `[template.plugins.default]` table." msgstr "" -#: ../../tutorials/get-to-know-hatch.md:68 +#: ../../tutorials/get-to-know-hatch.md:141 msgid "" "While tests are important, setting the tests configuration in Hatch to " "`true` will create a more complex `pyproject.toml` file. You won't need " @@ -1030,11 +1145,11 @@ msgid "" " introduce it in later tutorials." msgstr "" -#: ../../tutorials/get-to-know-hatch.md:73 +#: ../../tutorials/get-to-know-hatch.md:146 msgid "Your `config.toml` file should look something like the one below." msgstr "" -#: ../../tutorials/get-to-know-hatch.md:111 +#: ../../tutorials/get-to-know-hatch.md:184 msgid "" "Also notice that the default license option is MIT. While we will discuss" " license in more detail in a later lesson, the MIT license is the " @@ -1043,11 +1158,11 @@ msgid "" "use it for this tutorial series." msgstr "" -#: ../../tutorials/get-to-know-hatch.md:116 +#: ../../tutorials/get-to-know-hatch.md:190 msgid "You are of course welcome to select another license." msgstr "" -#: ../../tutorials/get-to-know-hatch.md:118 +#: ../../tutorials/get-to-know-hatch.md:192 #: ../../tutorials/installable-code.md:22 #: ../../tutorials/installable-code.md:411 #: ../../tutorials/installable-code.md:502 ../../tutorials/intro.md:226 @@ -1056,84 +1171,84 @@ msgstr "" msgid "Todo" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:119 +#: ../../tutorials/get-to-know-hatch.md:193 msgid "" "I think we'd need the SPDX license options here if they want to chose " "bsd-3 for instance" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:122 +#: ../../tutorials/get-to-know-hatch.md:196 msgid "Step 4: Close the config file and run `hatch config show`" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:124 +#: ../../tutorials/get-to-know-hatch.md:198 msgid "" "Once you have completed the steps above run the following command in your" " shell." msgstr "" -#: ../../tutorials/get-to-know-hatch.md:126 +#: ../../tutorials/get-to-know-hatch.md:200 msgid "`hatch config show`" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:128 +#: ../../tutorials/get-to-know-hatch.md:202 msgid "" "`hatch config show` will print out the contents of your `config.toml` " "file in your shell. look at the values and ensure that your name, email " "is set. Also make sure that `tests=false`." msgstr "" -#: ../../tutorials/get-to-know-hatch.md:130 +#: ../../tutorials/get-to-know-hatch.md:206 msgid "Hatch features" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:132 +#: ../../tutorials/get-to-know-hatch.md:208 msgid "" "Hatch offers a suite of features that will make creating, publishing and " "maintaining your Python package easier." msgstr "" -#: ../../tutorials/get-to-know-hatch.md:135 +#: ../../tutorials/get-to-know-hatch.md:211 msgid "Comparison to other tools" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:137 +#: ../../tutorials/get-to-know-hatch.md:213 msgid "" "[We compared Hatch to several of the other popular packaging tools in the" " ecosystem including flit, pdm and poetry. Learn more here](package-" "features)" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:140 +#: ../../tutorials/get-to-know-hatch.md:216 msgid "[More on Hatch here](hatch)" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:142 +#: ../../tutorials/get-to-know-hatch.md:218 msgid "A few features that Hatch offers" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:145 +#: ../../tutorials/get-to-know-hatch.md:220 msgid "" "it will convert metadata stored in a `setup.py` or `setup.cfg` file to a " "pyproject.toml file for you (see [Migrating setup.py to pyproject.toml " "using Hatch](setup-py-to-pyproject-toml.md ))" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:147 +#: ../../tutorials/get-to-know-hatch.md:222 msgid "" "It will help you by storing configuration information for publishing to " "PyPI after you've entered it once." msgstr "" -#: ../../tutorials/get-to-know-hatch.md:149 +#: ../../tutorials/get-to-know-hatch.md:224 msgid "Use `hatch -h` to see all of the available commands." msgstr "" -#: ../../tutorials/get-to-know-hatch.md:152 +#: ../../tutorials/get-to-know-hatch.md:226 msgid "What's next" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:154 +#: ../../tutorials/get-to-know-hatch.md:228 msgid "" "In the next lesson you'll learn how to package and make your code " "installable using Hatch." @@ -2038,6 +2153,10 @@ msgstr "" msgid "[epydoc](https://epydoc.sourceforge.net/epytext.html)" msgstr "" +#: ../../tutorials/intro.md:27 ../../tutorials/setup-py-to-pyproject-toml.md:24 +msgid "Get to know Hatch" +msgstr "" + #: ../../tutorials/intro.md:27 msgid "Python Packaging Tutorial Setup" msgstr "" @@ -5415,3 +5534,77 @@ msgid "" "existing functionality remains intact. Run any pre-existing tests to " "verify that everything still works as expected." msgstr "" + +#~ 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 "" + +#~ msgid "" +#~ "To begin, install Hatch from the " +#~ "command line using " +#~ "[pipx](https://pipx.pypa.io/stable/)" +#~ msgstr "" + +#~ 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 "" + +#~ msgid "" +#~ "You can check that hatch is " +#~ "working properly by issuing a simple " +#~ "command to get the version" +#~ msgstr "" + +#~ msgid "Note the version numbers will likely be different" +#~ msgstr "" + +#~ msgid "Configure hatch" +#~ msgstr "" + +#~ msgid "" +#~ "Once you have installed Hatch, you " +#~ "will want to customize the " +#~ "configuration." +#~ msgstr "" + +#~ msgid "" +#~ "Hatch stores your configuration information" +#~ " in a [`config.toml` " +#~ "file](https://hatch.pypa.io/latest/config/project-templates/)." +#~ msgstr "" + +#~ 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 "" + +#~ msgid "Step 1: Open and edit your `config.toml` file" +#~ msgstr "" + +#~ 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 "" + diff --git a/locales/ja/LC_MESSAGES/CONTRIBUTING.po b/locales/ja/LC_MESSAGES/CONTRIBUTING.po new file mode 100644 index 00000000..3c3eee6f --- /dev/null +++ b/locales/ja/LC_MESSAGES/CONTRIBUTING.po @@ -0,0 +1,436 @@ +# 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-08-02 18:04+0900\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: ja\n" +"Language-Team: ja \n" +"Plural-Forms: nplurals=1; plural=0;\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. To " +"\"fork\" a repository in GitHub means to create a copy of the main " +"repository, or repo, that you have complete control over and can modify " +"as you see fit." +msgstr "" + +#: ../../CONTRIBUTING.md:37 +msgid "To fork a repo," +msgstr "" + +#: ../../CONTRIBUTING.md:39 +msgid "Make sure you are logged into GitHub." +msgstr "" + +#: ../../CONTRIBUTING.md:41 +msgid "" +"Go to the repo you would like to fork, in this case the [Python Packaging" +" Guide](https://www.github.com/pyopensci/python-package-guide) repo." +msgstr "" + +#: ../../CONTRIBUTING.md:43 +msgid "" +"In the top right-hand corner of the page there is a 'Fork' button. Click " +"that button. You will be brought to a new page where you will 'Create a " +"new fork'. Feel free to keep all the default inputs and click 'Create " +"fork'. This will create a copy of the repo at " +"`https://github.com//python-package-guide`, where `` " +"is your GitHub username." +msgstr "" + +#: ../../CONTRIBUTING.md:47 +msgid "Contributing via the GitHub website" +msgstr "" + +#: ../../CONTRIBUTING.md:49 +msgid "How to edit a MarkDown file" +msgstr "" + +#: ../../CONTRIBUTING.md:51 +msgid "" +"*__TODO__: This section should show how to use the GitHub interface to " +"edit and previewing a Markdown file.*" +msgstr "" + +#: ../../CONTRIBUTING.md:53 +msgid "How to commit your changes" +msgstr "" + +#: ../../CONTRIBUTING.md:55 +msgid "" +"*__TODO__: This section should show how to commit changes via the GitHub " +"interface.*" +msgstr "" + +#: ../../CONTRIBUTING.md:57 +msgid "Contributing locally on your computer" +msgstr "" + +#: ../../CONTRIBUTING.md:59 +msgid "Clone your forked repository" +msgstr "" + +#: ../../CONTRIBUTING.md:61 +msgid "" +"*__TODO__: This section should show how to clone a repository from GitHub" +" into your computer.*" +msgstr "" + +#: ../../CONTRIBUTING.md:63 +msgid "Create a new branch" +msgstr "" + +#: ../../CONTRIBUTING.md:65 +msgid "*__TODO__: This section should show how to create a new branch.*" +msgstr "" + +#: ../../CONTRIBUTING.md:67 +msgid "Create a virtual environment" +msgstr "" + +#: ../../CONTRIBUTING.md:69 +msgid "" +"*__TODO__: This section should show how to create a virtual environment " +"using venv.*" +msgstr "" + +#: ../../CONTRIBUTING.md:71 +msgid "Install the development dependencies" +msgstr "" + +#: ../../CONTRIBUTING.md:73 +msgid "" +"*__TODO__: This section should show how to install the development " +"dependencies defined in pyproject.toml.*" +msgstr "" + +#: ../../CONTRIBUTING.md:75 +msgid "Commit your changes" +msgstr "" + +#: ../../CONTRIBUTING.md:77 +msgid "" +"*__TODO__: This section should describe how to commit from the command " +"line.*" +msgstr "" + +#: ../../CONTRIBUTING.md:79 +msgid "How to build the guide locally" +msgstr "" + +#: ../../CONTRIBUTING.md:81 +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:83 +msgid "Before you submit your pull request" +msgstr "" + +#: ../../CONTRIBUTING.md:85 +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:87 +msgid "Submitting a pull request with your contribution" +msgstr "" + +#: ../../CONTRIBUTING.md:89 +msgid "How to make a pull request" +msgstr "" + +#: ../../CONTRIBUTING.md:91 +msgid "" +"*__TODO__: This section should describe how to make a pull request in " +"GitHub.*" +msgstr "" + +#: ../../CONTRIBUTING.md:93 +msgid "What happens when you submit a pull request (CI/CD)" +msgstr "" + +#: ../../CONTRIBUTING.md:95 +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:97 +msgid "What to expect from the review process" +msgstr "" + +#: ../../CONTRIBUTING.md:99 +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:101 +msgid "Additional help" +msgstr "" + +#: ../../CONTRIBUTING.md:103 +msgid "How to get help" +msgstr "" + +#: ../../CONTRIBUTING.md:105 +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:107 +msgid "Additional resources" +msgstr "" + +#: ../../CONTRIBUTING.md:109 +msgid "" +"*__TODO__: It should also include links to beginner documentation, like " +"the GitHub docs.*" +msgstr "" + +#: ../../CONTRIBUTING.md:111 +msgid "Annex" +msgstr "" + +#: ../../CONTRIBUTING.md:113 +msgid "Code examples" +msgstr "" + +#: ../../CONTRIBUTING.md:115 +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:119 +msgid "Referencing code in documentation" +msgstr "" + +#: ../../CONTRIBUTING.md:121 +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:124 +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:129 +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:133 +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:136 +msgid "Creating code for documentation" +msgstr "" + +#: ../../CONTRIBUTING.md:138 +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:142 +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:146 +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:150 +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:153 +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:161 +msgid "Example:" +msgstr "" + +#: ../../CONTRIBUTING.md:163 +msgid "Instead of writing example code in markdown like this" +msgstr "" + +#: ../../CONTRIBUTING.md:174 +msgid "The python can be extracted into a `.py` file" +msgstr "" + +#: ../../CONTRIBUTING.md:188 +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:191 +msgid "Instead of writing this" +msgstr "" + +#: ../../CONTRIBUTING.md:203 +msgid "an example could be extracted from an existing toml file" +msgstr "" + diff --git a/locales/ja/LC_MESSAGES/TRANSLATING.po b/locales/ja/LC_MESSAGES/TRANSLATING.po new file mode 100644 index 00000000..707de067 --- /dev/null +++ b/locales/ja/LC_MESSAGES/TRANSLATING.po @@ -0,0 +1,718 @@ +# 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-08-02 18:04+0900\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: ja\n" +"Language-Team: ja \n" +"Plural-Forms: nplurals=1; plural=0;\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/ja/LC_MESSAGES/documentation.po b/locales/ja/LC_MESSAGES/documentation.po new file mode 100644 index 00000000..8a849f4a --- /dev/null +++ b/locales/ja/LC_MESSAGES/documentation.po @@ -0,0 +1,2546 @@ +# 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-08-02 18:04+0900\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: ja\n" +"Language-Team: ja \n" +"Plural-Forms: nplurals=1; plural=0;\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://pyopensci.org/badges/peer-" +"reviewed.svg)](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/ja/LC_MESSAGES/index.po b/locales/ja/LC_MESSAGES/index.po new file mode 100644 index 00000000..6d662248 --- /dev/null +++ b/locales/ja/LC_MESSAGES/index.po @@ -0,0 +1,484 @@ +# 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-08-02 18:04+0900\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: ja\n" +"Language-Team: ja \n" +"Plural-Forms: nplurals=1; plural=0;\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" + +#: ../../index.md:283 +msgid "Tutorials" +msgstr "" + +#: ../../index.md:289 +msgid "Packaging" +msgstr "" + +#: ../../index.md:139 ../../index.md:297 +msgid "Documentation" +msgstr "" + +#: ../../index.md:187 ../../index.md:305 +msgid "Tests" +msgstr "" + +#: ../../index.md:305 +msgid "Testing" +msgstr "" + +#: ../../index.md:1 +msgid "pyOpenSci Python Package Guide" +msgstr "" + +#: ../../index.md:3 +msgid "" +"We support the Python tools that scientists need to create open science " +"workflows." +msgstr "" + +#: ../../index.md:20 +msgid "" +"![GitHub release (latest by " +"date)](https://img.shields.io/github/v/release/pyopensci/python-package-" +"guide?color=purple&display_name=tag&style=plastic) " +"[![](https://img.shields.io/github/stars/pyopensci/python-package-" +"guide?style=social)](https://github.com/pyopensci/contributing-guide) " +"[![DOI](https://zenodo.org/badge/556814582.svg)](https://zenodo.org/badge/latestdoi/556814582)" +msgstr "" + +#: ../../index.md:20 +msgid "GitHub release (latest by date)" +msgstr "" + +#: ../../index.md:20 +msgid "DOI" +msgstr "" + +#: ../../index.md:27 +msgid "About this guide" +msgstr "" + +#: ../../index.md:29 +msgid "" +"Image with the pyOpenSci flower logo in the upper right hand corner. The " +"image shows the packaging lifecycle. The graphic shows a high level " +"overview of the elements of a Python package. the inside circle has 5 " +"items - user documentation, code/api, test suite, contributor " +"documentation, project metadata / license / readme. In the middle of the " +"circle is says maintainers and has a small icon with people. on the " +"outside circle there is an arrow and it says infrastructure." +msgstr "" + +#: ../../index.md:35 +msgid "This guide will help you:" +msgstr "" + +#: ../../index.md:37 +msgid "Learn how to create a Python package from start to finish" +msgstr "" + +#: ../../index.md:38 +msgid "Understand the broader Python packaging tool ecosystem" +msgstr "" + +#: ../../index.md:39 +msgid "Navigate and make decisions around tool options" +msgstr "" + +#: ../../index.md:40 +msgid "Understand all of the pieces of creating and maintaining a Python package" +msgstr "" + +#: ../../index.md:42 +msgid "" +"You will also find best practice recommendations and curated lists of " +"community resources surrounding packaging and package documentation." +msgstr "" + +#: ../../index.md:46 +msgid "Todo" +msgstr "" + +#: ../../index.md:47 +msgid "TODO: change the navigation of docs to have a" +msgstr "" + +#: ../../index.md:49 +msgid "user documentation contributor / maintainer documentation" +msgstr "" + +#: ../../index.md:51 +msgid "development guide" +msgstr "" + +#: ../../index.md:52 +msgid "contributing guide" +msgstr "" + +#: ../../index.md:54 +msgid "Community docs" +msgstr "" + +#: ../../index.md:55 +msgid "readme, coc, license" +msgstr "" + +#: ../../index.md:57 +msgid "Publish your docs" +msgstr "" + +#: ../../index.md:59 +msgid "_new_ Tutorial Series: Create a Python Package" +msgstr "" + +#: ../../index.md:61 +msgid "" +"The first round of our community-developed, how to create a Python " +"package tutorial series for scientists is complete! Join our community " +"review process or watch development of future tutorials in our [Github " +"repo here](https://github.com/pyOpenSci/python-package-guide)." +msgstr "" + +#: ../../index.md:71 +msgid "✿ Create a Package Tutorials ✿" +msgstr "" + +#: ../../index.md:75 +msgid "[What is a Python package?](/tutorials/intro)" +msgstr "" + +#: ../../index.md:76 +msgid "[Make your code installable](/tutorials/installable-code)" +msgstr "" + +#: ../../index.md:77 +msgid "[Publish your package to (test) PyPI](/tutorials/publish-pypi)" +msgstr "" + +#: ../../index.md:78 +msgid "[Publish your package to conda-forge](/tutorials/publish-conda-forge)" +msgstr "" + +#: ../../index.md:83 +msgid "✿ Package Metadata Tutorials ✿" +msgstr "" + +#: ../../index.md:87 +msgid "[How to add a README file](/tutorials/add-readme)" +msgstr "" + +#: ../../index.md:88 +msgid "" +"[How to add metadata to a pyproject.toml file for publication to " +"PyPI.](/tutorials/pyproject-toml.md)" +msgstr "" + +#: ../../index.md:93 +msgid "✿ Packaging Tool Tutorials ✿" +msgstr "" + +#: ../../index.md:97 +msgid "[Introduction to Hatch](/tutorials/get-to-know-hatch)" +msgstr "" + +#: ../../index.md:102 +msgid "Python Packaging for Scientists" +msgstr "" + +#: ../../index.md:104 +msgid "" +"Learn about Python packaging best practices. You will also get to know " +"the the vibrant ecosystem of packaging tools that are available to help " +"you with your Python packaging needs." +msgstr "" + +#: ../../index.md:113 +msgid "✨ Create your package ✨" +msgstr "" + +#: ../../index.md:117 +msgid "[Package file structure](/package-structure-code/python-package-structure)" +msgstr "" + +#: ../../index.md:118 +msgid "" +"[Package metadata / pyproject.toml](package-structure-code/pyproject-" +"toml-python-package-metadata.md)" +msgstr "" + +#: ../../index.md:119 +msgid "" +"[Build your package (sdist / wheel)](package-structure-code/python-" +"package-distribution-files-sdist-wheel.md)" +msgstr "" + +#: ../../index.md:120 +msgid "[Declare dependencies](package-structure-code/declare-dependencies.md)" +msgstr "" + +#: ../../index.md:121 +msgid "" +"[Navigate the packaging tool ecosystem](package-structure-code/python-" +"package-build-tools.md)" +msgstr "" + +#: ../../index.md:122 +msgid "" +"[Non pure Python builds](package-structure-code/complex-python-package-" +"builds.md)" +msgstr "" + +#: ../../index.md:127 +msgid "✨ Publish your package ✨" +msgstr "" + +#: ../../index.md:131 +msgid "" +"Gain a better understanding of the Python packaging ecosystem Learn about" +" best practices for:" +msgstr "" + +#: ../../index.md:134 +msgid "" +"[Package versioning & release](/package-structure-code/python-package-" +"versions.md)" +msgstr "" + +#: ../../index.md:135 +msgid "" +"[Publish to PyPI & Conda-forge](/package-structure-code/publish-python-" +"package-pypi-conda.md)" +msgstr "" + +#: ../../index.md:148 +msgid "✨ Write The Docs ✨" +msgstr "" + +#: ../../index.md:151 +msgid "" +"[Create documentation for your users](/documentation/write-user-" +"documentation/intro)" +msgstr "" + +#: ../../index.md:152 +msgid "" +"[Core files to include in your package repository](/documentation" +"/repository-files/intro)" +msgstr "" + +#: ../../index.md:153 +msgid "" +"[Write tutorials to show how your package is used](/documentation/write-" +"user-documentation/create-package-tutorials)" +msgstr "" + +#: ../../index.md:158 +msgid "✨ Developer Docs ✨" +msgstr "" + +#: ../../index.md:161 +msgid "" +"[Create documentation for collaborating developers](/documentation" +"/repository-files/contributing-file)" +msgstr "" + +#: ../../index.md:162 +msgid "" +"[Write a development guide](/documentation/repository-files/development-" +"guide)" +msgstr "" + +#: ../../index.md:167 +msgid "✨ Document For A Community ✨" +msgstr "" + +#: ../../index.md:170 +msgid "" +"[Writing a README file](/documentation/repository-files/readme-file-best-" +"practices)" +msgstr "" + +#: ../../index.md:171 +msgid "" +"[Set norms with a Code of Conduct](/documentation/repository-files/code-" +"of-conduct-file)" +msgstr "" + +#: ../../index.md:172 +msgid "[License your package](/documentation/repository-files/license-files)" +msgstr "" + +#: ../../index.md:177 +msgid "✨ Publish Your Docs ✨" +msgstr "" + +#: ../../index.md:180 +msgid "[How to publish your docs](/documentation/hosting-tools/intro)" +msgstr "" + +#: ../../index.md:181 +msgid "[Using Sphinx](/documentation/hosting-tools/intro)" +msgstr "" + +#: ../../index.md:182 +msgid "" +"[Markdown, MyST, and ReST](/documentation/hosting-tools/myst-markdown-" +"rst-doc-syntax)" +msgstr "" + +#: ../../index.md:183 +msgid "" +"[Host your docs on Read The Docs or Github Pages](/documentation/hosting-" +"tools/publish-documentation-online)" +msgstr "" + +#: ../../index.md:189 +msgid "" +"*We are actively working on this section. [Follow development " +"here.](https://github.com/pyOpenSci/python-package-guide)*" +msgstr "" + +#: ../../index.md:197 +msgid "✨ Tests for your Python package ✨" +msgstr "" + +#: ../../index.md:200 +msgid "[Intro to testing](tests/index.md)" +msgstr "" + +#: ../../index.md:201 +msgid "[Write tests](tests/write-tests)" +msgstr "" + +#: ../../index.md:202 +msgid "[Types of tests](tests/test-types)" +msgstr "" + +#: ../../index.md:207 +msgid "✨ Run your tests ✨" +msgstr "" + +#: ../../index.md:210 +msgid "[Run tests locally](tests/run-tests)" +msgstr "" + +#: ../../index.md:211 +msgid "[Run tests in CI](tests/tests-ci)" +msgstr "" + +#: ../../index.md:215 +msgid "Contributing" +msgstr "" + +#: ../../index.md:225 +msgid "✨ Code style & Format ✨" +msgstr "" + +#: ../../index.md:230 +msgid "[Code style](package-structure-code/code-style-linting-format.md)" +msgstr "" + +#: ../../index.md:235 +msgid "✨ Want to contribute? ✨" +msgstr "" + +#: ../../index.md:240 +msgid "" +"We welcome contributions to this guide. Learn more about how you can " +"contribute." +msgstr "" + +#: ../../index.md:246 +msgid "" +"xkcd comic showing a stick figure on the ground and one in the air. The " +"one on the ground is saying. `You're flying! how?` The person in the air" +" replies `Python!` Below is a 3 rectangle comic with the following text " +"in each box. box 1 - I learned it last night. Everything is so simple. " +"Hello world is just print hello world. box 2 - the person on the ground " +"says - come join us programming is fun again. it's a whole new world. But" +" how are you flying? box 3 - the person flying says - i just typed import" +" antigravity. I also sampled everything in the medicine cabinet. But i " +"think this is the python. the person on the ground is saying - that's it?" +msgstr "" + +#: ../../index.md:252 +msgid "A community-created guidebook" +msgstr "" + +#: ../../index.md:254 +msgid "" +"Every page in this guidebook goes through an extensive community review " +"process. To ensure our guidebook is both beginner-friendly and accurate, " +"we encourage reviews from a diverse set of pythonistas and scientists " +"with a wide range of skills and expertise." +msgstr "" + +#: ../../index.md:257 +msgid "View guidebook contributors" +msgstr "" + +#: ../../index.md:265 +msgid "Who this guidebook is for" +msgstr "" + +#: ../../index.md:267 +msgid "" +"This guidebook is for anyone interested in learning more about Python " +"packaging. It is beginner-friendly and will provide:" +msgstr "" + +#: ../../index.md:269 +msgid "Beginning-to-end guidance on creating a Python package." +msgstr "" + +#: ../../index.md:270 +msgid "" +"Resources to help you navigate the Python packaging ecosystem of tools " +"and approaches to packaging." +msgstr "" + +#: ../../index.md:271 +msgid "" +"A curated list of resources to help you get your package into documented," +" usable and maintainable shape." +msgstr "" + +#: ../../index.md:273 +msgid "Where this guide is headed" +msgstr "" + +#: ../../index.md:275 +msgid "" +"If you have ideas of things you'd like to see here clarified in this " +"guide, [we invite you to open an issue on " +"GitHub.](https://github.com/pyOpenSci/python-package-guide/issues)." +msgstr "" + +#: ../../index.md:278 +msgid "" +"If you have questions about our peer review process or packaging in " +"general, you are welcome to use our [pyOpenSci Discourse " +"forum](https://pyopensci.discourse.group/)." +msgstr "" + +#: ../../index.md:280 +msgid "" +"This is a living guide that is updated as tools and best practices evolve" +" in the Python packaging ecosystem. We will be adding new content over " +"the next year." +msgstr "" + diff --git a/locales/ja/LC_MESSAGES/package-structure-code.po b/locales/ja/LC_MESSAGES/package-structure-code.po new file mode 100644 index 00000000..e409630c --- /dev/null +++ b/locales/ja/LC_MESSAGES/package-structure-code.po @@ -0,0 +1,5302 @@ +# 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-08-02 18:04+0900\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: ja\n" +"Language-Team: ja \n" +"Plural-Forms: nplurals=1; plural=0;\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:182 +msgid "Python file `temporal.py` imports after `isort` has been run" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:189 +msgid "Ruff" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:191 +msgid "" +"[Ruff](https://docs.astral.sh/ruff/) is a new addition to the code " +"quality ecosystem, gaining some traction since its release. `ruff` is " +"both a linter and a code formatter for Python, aiming to replace several " +"tools behind a single interface. As such, `ruff` can be used at a " +"replacement of all other tools mentioned here, or in complement to some " +"of them." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:197 +msgid "" +"`ruff` has some interesting features that distinguish it from other " +"linters:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:199 +msgid "Linter configuration in `pyproject.toml`" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:200 +msgid "Several hundred rules included, many of which are automatically fixable" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:201 +msgid "" +"Rules explanation, see [F403](https://docs.astral.sh/ruff/rules" +"/undefined-local-with-import-star/) for an example" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:202 +msgid "" +"Fast execution time, makes a quick feedback loop possible even on large " +"projects." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:204 +msgid "" +"Here is a simple configuration to get started with `ruff`. It would go " +"into your `pyproject.toml`:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:212 +msgid "" +"Depending on your project, you might want to add the following to sort " +"imports correctly:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:219 +msgid "How to use code formatter in your local workflow" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:221 +msgid "Linters, code formatters and your favorite coding tools" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:223 +msgid "" +"Linters can be run as a command-line tool as shown above. They also can " +"be run within your favorite coding tool (e.g. VScode, pycharm, etc). For " +"example, you might prefer to have tools like Black and isort run when you" +" save a file. In some editors you can also setup shortcuts that run your " +"favorite code format tools on demand." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:229 +msgid "Use pre-commit hooks to run code formatters and linters on commits" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:231 +msgid "You can also setup a `pre-commit hook` in your Python package repository." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:233 +msgid "" +"A pre-commit hook is a tool that allows an action (or actions) to be " +"triggered when you apply a commit to your git repository." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:236 +msgid "Pre-commit hook example workflow" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:238 +msgid "The precommit workflow looks like this: You type and run:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:241 +msgid "`git commit -m \"message here\"` at the command line" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:243 +msgid "" +"Once you hit return, pre-commit will run any tools that you have " +"configured in a **.pre-commit-config.yaml** file." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:245 +msgid "" +"If the tools configured in the pre-commit hook run successfully without " +"making changes or finding errors in your code, the commit will be applied" +" to the repository." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:249 +msgid "" +"If the tools configured in the hook find errors in your files, the commit" +" will NOT be applied to the repository. Remember from the discussion " +"above that a code formatter like Black will run and reformat your code. A" +" linter like _flake8_ will provide you with some output that details " +"where there are syntax issues in your code. You will then need to fix " +"those issues, manually." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:256 +msgid "" +"Once all of the fixes are applied you can re-add (stage) the files to be " +"commit. And re-run your commit." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:260 +msgid "Diagram showing the steps of a pre-commit workflow from left to right." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:262 +msgid "" +"The pre-commit workflow begins with you adding files that have changes to" +" be staged in git. Next, you'd run git commit. when you run git commit, " +"the pre-commit hooks will then run. In this example, Black, the code " +"formatter and flake8, a linter both run. If all of the files pass Black " +"and flake8 checks, then your commit will be recorded. If they don't, the " +"commit is canceled. You will have to fix any flake8 issues, and then re-" +"add / stage the files to be committed. [_Image " +"Source_](https://ljvmiranda921.github.io/notebook/2018/06/21/precommits-" +"using-black-and-flake8/*)" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:275 +msgid "" +"If have a Python code-base and multiple maintainers actively working on " +"the code, and you intend to run a tool like Black, be sure to coordinate " +"across your team. An initial commit that applies Black to your entire " +"package will likely change a significant amount of your code. This could " +"lead to merge conflicts on open and new PR's before the new changes are " +"merged." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:282 +msgid "General pre commit checks" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:284 +msgid "" +"In addition to calling tools, Pre-commit also has a suite of [built in " +"format hooks](https://github.com/pre-commit/pre-commit-hooks#hooks-" +"available) that you can call. Some, such as trailing-whitespace can be " +"also useful to add to your pre-commit workflow to ensure clean, " +"streamlined code files." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:289 +msgid "" +"An example pre-commit-config.yaml file is below with examples of how this" +" is all setup." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:292 +msgid "Pre-commit.ci" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:294 +msgid "" +"[Pre-commit.ci](https://pre-commit.ci) is a bot that may become your new " +"best friend. This bot, when setup on a repo can be configured to do the " +"following:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:297 +msgid "It will check every pull request using all of the pre-commit hook setting" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:298 +msgid "" +"If you wish, it will also submit a pull request to your repo with pre-" +"commit fixes, saving you, and new contributors the time of reformatting a" +" pr that has format issues." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:301 +msgid "You can also call the bot on any pull request to run / and fix the code." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:303 +msgid "" +"The pre-commit.ci bot uses the same pre-commit-config.yaml file that you " +"use to setup pre-commit locally." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:306 +msgid "Setting up a bot like this can be valuable because:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:308 +msgid "" +"It can make is easier for maintainers as they no longer have to worry at " +"allows about fixing code format. The bot will do the work for them." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:310 +msgid "" +"It can make it easier for new comers as they never have to setup pre-" +"commit locally or worry about linting their code. They can even make " +"small fixes to the code directly on GitHub without worry." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:312 +msgid "Setting up a git pre-commit hook" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:314 +msgid "To setup pre-commit locally, you need to do 3 things:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:316 +msgid "" +"Install pre-commit (and include it as a development requirement in your " +"repository)" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:326 +msgid "" +"Create a .pre-commit-config.yaml file in the root of your package " +"directory." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:328 +msgid "" +"Below is an example **.pre-commit-cofig.yaml** file that can be used to " +"setup the pre-commit hook and the pre-commit.ci bot if you chose to " +"implement that too." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:336 +msgid "" +"This file specifies a hook that will be triggered automatically before " +"each `git commit`, in this case, it specifies a `flake8` using version " +"`6.0.0`." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:339 +msgid "" +"Install your pre-commit hook(s) using `pre-commit install`. This will " +"install all of the hooks specified in the pre-commit yaml file into your " +"environment." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:341 +msgid "" +"Once you have done the above, you are ready to start working on your " +"code. Pre-commit will run every time you run `git commit`." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:344 +msgid "Summary" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:346 +msgid "" +"pyOpenSci suggests setting up a linter and a code styler for your " +"package, regardless of whether you use pre-commit hooks, CI or other " +"infrastructure to manage code format. Setting up these tools will give " +"you automatic feedback about your code's structure as you (or a " +"contributor) write it. And using a tool like black that format code for " +"you, reduce effort that you need to make surrounding decisions around " +"code format and style." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:1 +msgid "Complex Python package builds" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:3 +msgid "" +"This guide is focused on packages that are either pure-python or that " +"have a few simple extensions in another language such as C or C++." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:6 +msgid "" +"In the future, we want to provide resources for packaging workflows that " +"require more complex builds. If you have questions about these types of " +"package, please [add a question to our " +"discourse](https://pyopensci.discourse.group/) or open an [issue about " +"this guide specifically in the GitHub repo for this " +"guide](https://github.com/pyOpenSci/python-package-guide/issues). There " +"are many nuances to building and distributing Python packages that have " +"compiled extensions requiring non-Python dependencies at build time. For " +"an overview and thorough discussion of these nuances, please see [this " +"site.](https://pypackaging-native.github.io/)" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:8 +msgid "Pure Python Packages vs. packages with extensions in other languages" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:10 +msgid "" +"You can classify Python package complexity into three general categories." +" These categories can in turn help you select the correct package " +"frontend and backend tools." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:14 +msgid "" +"**Pure-python packages:** these are packages that only rely on Python to " +"function. Building a pure Python package is simpler. As such, you can " +"chose a tool below that has the features that you want and be done with " +"your decision!" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:16 +msgid "" +"**Python packages with non-Python extensions:** These packages have " +"additional components called extensions written in other languages (such " +"as C or C++). If you have a package with non-Python extensions, then you " +"need to select a build backend tool that allows additional build steps " +"needed to compile your extension code. Further, if you wish to use a " +"frontend tool to support your workflow, you will need to select a tool " +"that supports additional build setups. We suggest that you chose build " +"tool that supports custom build steps like Hatch." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:18 +msgid "" +"**Python packages that have extensions written in different languages " +"(e.g. Fortran and C++) or that have non Python dependencies that are " +"difficult to install (e.g. GDAL)** These packages often have complex " +"build steps (more complex than a package with just a few C extensions for" +" instance). As such, these packages require tools such as [scikit-" +"build](https://scikit-build.readthedocs.io/en/latest/) or [meson-" +"python](https://mesonbuild.com/Python-module.html) to build. NOTE: you " +"can use meson-python with PDM." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:21 +msgid "Mixing frontend and backend projects" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:23 +msgid "" +"It is sometimes necessary or desirable to use a build frontend with an " +"alternative build-backend. This is because some frontends do not have a " +"default backend (`build`), and this choice is placed on the maintainer. " +"Other backends (`hatch`) have a preferred backend (`hatchling`) but allow" +" the maintainer to migrate to another, while some backends (`poetry`) " +"only work with a single backend (`poetry-core`). Refer to (#python-" +"package-build-tools) for more information about frontend and backend " +"compatibility." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:29 +msgid "" +"In this packaging guide we recommend using `hatch` along with its " +"preferred backend `hatchling`. While this will be suitable for most " +"packages, an alternate backend may be used with Hatch if needed when " +"creating an extension module. A Python extension module is one that is " +"made up, either in part or entirely, of compiled code. In this case the " +"backend chosen (such as `meson-python`) must know how to compile the " +"extension language and bind it to Python. `hatchling` does not know how " +"to do this all on its own and must either make use of " +"[plugins](https://hatch.pypa.io/1.9/plugins/about/) or be replaced by a " +"backend that is already capable of building extension modules." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:37 +msgid "" +"In order to use a different backend you will need to edit your project's " +"`pyproject.toml`. If you have a `pyproject.toml` generated by the `hatch`" +" command, or from following the packaging tutorial, you may have to make " +"a change like this" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:8 +#: ../../package-structure-code/declare-dependencies.md:375 +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md: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/ja/LC_MESSAGES/tests.po b/locales/ja/LC_MESSAGES/tests.po new file mode 100644 index 00000000..540e03ab --- /dev/null +++ b/locales/ja/LC_MESSAGES/tests.po @@ -0,0 +1,1003 @@ +# 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-08-02 18:04+0900\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: ja\n" +"Language-Team: ja \n" +"Plural-Forms: nplurals=1; plural=0;\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" + +#: ../../tests/index.md:72 +msgid "Intro" +msgstr "" + +#: ../../tests/index.md:72 +msgid "Write tests" +msgstr "" + +#: ../../tests/index.md:72 +msgid "Test types" +msgstr "" + +#: ../../tests/index.md:72 +msgid "Run tests locally" +msgstr "" + +#: ../../tests/index.md:72 +msgid "Run tests online (using CI)" +msgstr "" + +#: ../../tests/index.md:72 +msgid "Create & Run Tests" +msgstr "" + +#: ../../tests/index.md:1 +msgid "Tests and data for your Python package" +msgstr "" + +#: ../../tests/index.md:3 +msgid "" +"Tests are an important part of your Python package because they provide a" +" set of checks that ensure that your package is functioning how you " +"expect it to." +msgstr "" + +#: ../../tests/index.md:7 +msgid "" +"In this section you will learn more about the importance of writing tests" +" for your Python package and how you can setup infrastructure to run your" +" tests both locally and on GitHub." +msgstr "" + +#: ../../tests/index.md:19 +msgid "✨ Why write tests ✨" +msgstr "" + +#: ../../tests/index.md:24 +msgid "" +"Learn more about the art of writing tests for your Python package. Learn " +"about why you should write tests and how they can help you and potential " +"contributors to your project." +msgstr "" + +#: ../../tests/index.md:31 +msgid "✨ Types of tests ✨" +msgstr "" + +#: ../../tests/index.md:36 +msgid "" +"There are three general types of tests that you can write for your Python" +" package: unit tests, integration tests and end-to-end (or functional) " +"tests. Learn about all three." +msgstr "" + +#: ../../tests/index.md:42 +msgid "✨ Run tests locally ✨" +msgstr "" + +#: ../../tests/index.md:47 +msgid "" +"If you expect your users to use your package across different versions of" +" Python, then using an automation tool such as nox to run your tests is " +"useful. Learn about the various tools that you can use to run your tests " +"across python versions here." +msgstr "" + +#: ../../tests/index.md:53 +msgid "✨ Run tests online (using CI) ✨" +msgstr "" + +#: ../../tests/index.md:58 +msgid "" +"Continuous integration platforms such as GitHub actions can be useful for" +" running your tests across both different Python versions and different " +"operating systems. Learn about setting up tests to run in Continuous " +"Integration here." +msgstr "" + +#: ../../tests/index.md:69 +msgid "Graphic showing the elements of the packaging process." +msgstr "" + +#: ../../tests/run-tests.md:6 +msgid "Run Python package tests" +msgstr "" + +#: ../../tests/run-tests.md:8 +msgid "" +"Running your tests is important to ensure that your package is working as" +" expected. It's good practice to consider that tests will run on your " +"computer and your users' computers that may be running a different Python" +" version and operating systems. Think about the following when running " +"your tests:" +msgstr "" + +#: ../../tests/run-tests.md:11 +msgid "" +"Run your test suite in a matrix of environments that represent the Python" +" versions and operating systems your users are likely to have." +msgstr "" + +#: ../../tests/run-tests.md:12 +msgid "" +"Running your tests in an isolated environment provides confidence in the " +"tests and their reproducibility. This ensures that tests do not pass " +"randomly due to your computer's specific setup. For instance, you might " +"have unexpectedly installed dependencies on your local system that are " +"not declared in your package's dependency list. This oversight could lead" +" to issues when others try to install or run your package on their " +"computers." +msgstr "" + +#: ../../tests/run-tests.md:14 +msgid "" +"On this page, you will learn about the tools that you can use to both run" +" tests in isolated environments and across Python versions." +msgstr "" + +#: ../../tests/run-tests.md:19 +msgid "Tools to run your tests" +msgstr "" + +#: ../../tests/run-tests.md:21 +msgid "" +"There are three categories of tools that will make is easier to setup and" +" run your tests in various environments:" +msgstr "" + +#: ../../tests/run-tests.md:24 +msgid "" +"A **test framework**, is a package that provides a particular syntax and " +"set of tools for _both writing and running your tests_. Some test " +"frameworks also have plugins that add additional features such as " +"evaluating how much of your code the tests cover. Below you will learn " +"about the **pytest** framework which is one of the most commonly used " +"Python testing frameworks in the scientific ecosystem. Testing frameworks" +" are essential but they only serve to run your tests. These frameworks " +"don't provide a way to easily run tests across Python versions without " +"the aid of additional automation tools." +msgstr "" + +#: ../../tests/run-tests.md:25 +msgid "" +"**Automation tools** allow you to automate running workflows such as " +"tests in specific ways using user-defined commands. For instance it's " +"useful to be able to run tests across different Python versions with a " +"single command. Tools such as " +"[**nox**](https://nox.thea.codes/en/stable/index.html) and " +"[**tox**](https://tox.wiki/en/latest/index.html) also allow you to run " +"tests across Python versions. However, it will be difficult to test your " +"build on different operating systems using only nox and tox - this is " +"where continuous integration (CI) comes into play." +msgstr "" + +#: ../../tests/run-tests.md:26 +msgid "" +"**Continuous Integration (CI):** is the last tool that you'll need to run" +" your tests. CI will not only allow you to replicate any automated builds" +" you create using nox or tox to run your package in different Python " +"environments. It will also allow you to run your tests on different " +"operating systems (Windows, Mac and Linux). [We discuss using CI to run " +"tests here](tests-ci)." +msgstr "" + +#: ../../tests/run-tests.md:28 +msgid "Table: Testing & Automation Tool" +msgstr "" + +#: ../../tests/run-tests.md:35 +msgid "Features" +msgstr "" + +#: ../../tests/run-tests.md:36 +msgid "Testing Framework (pytest)" +msgstr "" + +#: ../../tests/run-tests.md:37 +msgid "Test Runner (Tox)" +msgstr "" + +#: ../../tests/run-tests.md:38 +msgid "Automation Tools (Nox)" +msgstr "" + +#: ../../tests/run-tests.md:39 +msgid "Continuous Integration (GitHub Actions)" +msgstr "" + +#: ../../tests/run-tests.md:40 +msgid "Run Tests Locally" +msgstr "" + +#: ../../tests/run-tests.md:41 ../../tests/run-tests.md:42 +#: ../../tests/run-tests.md:43 ../../tests/run-tests.md:49 +#: ../../tests/run-tests.md:52 ../../tests/run-tests.md:53 +#: ../../tests/run-tests.md:54 ../../tests/run-tests.md:57 +#: ../../tests/run-tests.md:58 ../../tests/run-tests.md:59 +#: ../../tests/run-tests.md:64 ../../tests/run-tests.md:68 +#: ../../tests/run-tests.md:69 +msgid "" +msgstr "" + +#: ../../tests/run-tests.md:44 ../../tests/run-tests.md:46 +#: ../../tests/run-tests.md:47 ../../tests/run-tests.md:48 +#: ../../tests/run-tests.md:51 ../../tests/run-tests.md:56 +#: ../../tests/run-tests.md:61 ../../tests/run-tests.md:62 +#: ../../tests/run-tests.md:63 ../../tests/run-tests.md:66 +#: ../../tests/run-tests.md:67 +msgid "" +msgstr "" + +#: ../../tests/run-tests.md:45 +msgid "Run Tests Online" +msgstr "" + +#: ../../tests/run-tests.md:50 +msgid "Run Tests Across Python Versions" +msgstr "" + +#: ../../tests/run-tests.md:55 +msgid "Run Tests In Isolated Environments" +msgstr "" + +#: ../../tests/run-tests.md:60 +msgid "Run Tests Across Operating Systems (Windows, MacOS, Linux)" +msgstr "" + +#: ../../tests/run-tests.md:65 +msgid "Use for other automation tasks (e.g. building docs)" +msgstr "" + +#: ../../tests/run-tests.md:73 +msgid "What testing framework / package should I use to run tests?" +msgstr "" + +#: ../../tests/run-tests.md:75 +msgid "" +"We recommend using `Pytest` to build and run your package tests. Pytest " +"is the most common testing tool used in the Python ecosystem." +msgstr "" + +#: ../../tests/run-tests.md:77 +msgid "" +"[The Pytest package](https://docs.pytest.org/en/latest/) also has a " +"number of extensions that can be used to add functionality such as:" +msgstr "" + +#: ../../tests/run-tests.md:80 +msgid "" +"[pytest-cov](https://pytest-cov.readthedocs.io/en/latest/) allows you to " +"analyze the code coverage of your package during your tests, and " +"generates a report that you can [upload to codecov](https://codecov.io/)." +msgstr "" + +#: ../../tests/run-tests.md:82 ../../tests/run-tests.md:174 +#: ../../tests/test-types.md:14 ../../tests/tests-ci.md:7 +msgid "Todo" +msgstr "" + +#: ../../tests/run-tests.md:83 +msgid "Learn more about code coverage here. (add link)" +msgstr "" + +#: ../../tests/run-tests.md:87 +msgid "" +"Your editor or IDE may add additional convenience for running tests, " +"setting breakpoints, and toggling the `–no-cov` flag. Check your editor's" +" documentation for more information." +msgstr "" + +#: ../../tests/run-tests.md:90 +msgid "Run tests using pytest" +msgstr "" + +#: ../../tests/run-tests.md:92 +msgid "If you are using **pytest**, you can run your tests locally by calling:" +msgstr "" + +#: ../../tests/run-tests.md:95 +msgid "`pytest`" +msgstr "" + +#: ../../tests/run-tests.md:97 +msgid "" +"Or if you want to run a specific test file - let's call this file " +"\"`test_module.py`\" - you can run:" +msgstr "" + +#: ../../tests/run-tests.md:99 +msgid "`pytest test_module.py`" +msgstr "" + +#: ../../tests/run-tests.md:101 +msgid "" +"Learn more from the [get started docs](https://docs.pytest.org/en/7.1.x" +"/getting-started.html)." +msgstr "" + +#: ../../tests/run-tests.md:103 +msgid "" +"Running pytest on your computer is going to run your tests in whatever " +"Python environment you currently have activated. This means that tests " +"will be run on a single version of Python and only on the operating " +"system that you are running locally." +msgstr "" + +#: ../../tests/run-tests.md:108 +msgid "" +"An automation tool can simplify the process of running tests in various " +"Python environments." +msgstr "" + +#: ../../tests/run-tests.md:111 +msgid "Tests across operating systems" +msgstr "" + +#: ../../tests/run-tests.md:112 +msgid "" +"If you want to run your tests across different operating systems you can " +"[continuous integration. Learn more here](tests-ci)." +msgstr "" + +#: ../../tests/run-tests.md:115 +msgid "Tools to automate running your tests" +msgstr "" + +#: ../../tests/run-tests.md:117 +msgid "" +"To run tests on various Python versions or in various specific " +"environments with a single command, you can use an automation tool such " +"as `nox` or `tox`. Both `nox` and `tox` can create an isolated virtual " +"environments. This allows you to easily run your tests in multiple " +"environments and across Python versions." +msgstr "" + +#: ../../tests/run-tests.md:120 +msgid "" +"We will focus on [Nox](https://nox.thea.codes/) in this guide. `nox` is a" +" Python-based automation tool that builds upon the features of both " +"`make` and `tox`. `nox` is designed to simplify and streamline testing " +"and development workflows. Everything that you do with `nox` can be " +"implemented using a Python-based interface." +msgstr "" + +#: ../../tests/run-tests.md:122 +msgid "Other automation tools you'll see in the wild" +msgstr "" + +#: ../../tests/run-tests.md:125 +msgid "" +"**[Tox](https://tox.wiki/en/latest/index.html#useful-links)** is an " +"automation tool that supports common steps such as building " +"documentation, running tests across various versions of Python, and more." +" You can find [a nice overview of tox in the plasmaPy " +"documentation](https://docs.plasmapy.org/en/stable/contributing/testing_guide.html" +"#using-tox)." +msgstr "" + +#: ../../tests/run-tests.md:127 +msgid "" +"**[Hatch](https://github.com/ofek/hatch)** is a modern end-to-end " +"packaging tool that works with the popular build backend called " +"hatchling. `hatch` offers a `tox`-like setup where you can run tests " +"locally using different Python versions. If you are using `hatch` to " +"support your packaging workflow, you may want to also use its testing " +"capabilities rather than using `nox`." +msgstr "" + +#: ../../tests/run-tests.md:129 +msgid "" +"[**make:**](https://www.gnu.org/software/make/manual/make.html) Some " +"developers use Make, which is a build automation tool, for running tests " +"due to its versatility; it's not tied to a specific language and can be " +"used to run various build processes. However, Make's unique syntax and " +"approach can make it more challenging to learn, particularly if you're " +"not already familiar with it. Make also won't manage environments for you" +" like **nox** will do." +msgstr "" + +#: ../../tests/run-tests.md:136 +msgid "Run tests across Python versions with nox" +msgstr "" + +#: ../../tests/run-tests.md:138 +msgid "**Nox** is a great automation tool to learn because it:" +msgstr "" + +#: ../../tests/run-tests.md:140 +msgid "Is Python-based making it accessible if you already know Python and" +msgstr "" + +#: ../../tests/run-tests.md:141 +msgid "Will create isolated environments to run workflows." +msgstr "" + +#: ../../tests/run-tests.md:143 +msgid "" +"`nox` simplifies creating and managing testing environments. With `nox`, " +"you can set up virtual environments, and run tests across Python versions" +" using the environment manager of your choice with a single command." +msgstr "" + +#: ../../tests/run-tests.md:148 +msgid "Nox Installations" +msgstr "" + +#: ../../tests/run-tests.md:150 +msgid "" +"When you install and use nox to run tests across different Python " +"versions, nox will create and manage individual `venv` environments for " +"each Python version that you specify in the nox function." +msgstr "" + +#: ../../tests/run-tests.md:152 +msgid "Nox will manage each environment on its own." +msgstr "" + +#: ../../tests/run-tests.md:154 +msgid "" +"Nox can also be used for other development tasks such as building " +"documentation, creating your package distribution, and testing " +"installations across both PyPI related environments (e.g. venv, " +"virtualenv) and `conda` (e.g. `conda-forge`)." +msgstr "" + +#: ../../tests/run-tests.md:158 +msgid "" +"To get started with nox, you create a `noxfile.py` file at the root of " +"your project directory. You then define commands using Python functions. " +"Some examples of that are below." +msgstr "" + +#: ../../tests/run-tests.md:162 +msgid "Test Environments" +msgstr "" + +#: ../../tests/run-tests.md:164 +msgid "" +"By default, `nox` uses the Python built in `venv` environment manager. A " +"virtual environment (`venv`) is a self-contained Python environment that " +"allows you to isolate and manage dependencies for different Python " +"projects. It helps ensure that project-specific libraries and packages do" +" not interfere with each other, promoting a clean and organized " +"development environment." +msgstr "" + +#: ../../tests/run-tests.md:166 +msgid "" +"An example of using nox to run tests in `venv` environments for Python " +"versions 3.9, 3.10, 3.11 and 3.12 is below." +msgstr "" + +#: ../../tests/run-tests.md:169 +msgid "" +"Note that for the code below to work, you need to have all 4 versions of " +"Python installed on your computer for `nox` to find." +msgstr "" + +#: ../../tests/run-tests.md:172 +msgid "Nox with venv environments" +msgstr "" + +#: ../../tests/run-tests.md:175 +msgid "" +"TODO: add some tests above and show what the output would look like in " +"the examples below..." +msgstr "" + +#: ../../tests/run-tests.md:178 +msgid "" +"Below is an example of setting up nox to run tests using `venv` which is " +"the built in environment manager that comes with base Python." +msgstr "" + +#: ../../tests/run-tests.md:180 +msgid "" +"Note that the example below assumes that you have [setup your " +"`pyproject.toml` to declare test dependencies in a way that pip can " +"understand](../package-structure-code/declare-dependencies.md). An " +"example of that setup is below." +msgstr "" + +#: ../../tests/run-tests.md:201 +msgid "" +"If you have the above setup, then you can use " +"`session.install(\".[tests]\")` to install your test dependencies. Notice" +" that below one single nox session allows you to run your tests on 4 " +"different Python environments (Python 3.9, 3.10, 3.11, and 3.12)." +msgstr "" + +#: ../../tests/run-tests.md:222 +msgid "" +"Above you create a nox session in the form of a function with a " +"`@nox.session` decorator. Notice that within the decorator you declare " +"the versions of python that you wish to run." +msgstr "" + +#: ../../tests/run-tests.md:226 +msgid "" +"To run the above you'd execute the following command, specifying which " +"session with `--session` (sometimes shortened to `-s`). Your function " +"above is called test, therefore the session name is test." +msgstr "" + +#: ../../tests/run-tests.md:234 +msgid "Nox with conda / mamba" +msgstr "" + +#: ../../tests/run-tests.md:236 +msgid "" +"Below is an example for setting up nox to use mamba (or conda) for your " +"environment manager. Note that unlike venv, conda can automatically " +"install the various versions of Python that you need. You won't need to " +"install all four Python versions if you use conda/mamba, like you do with" +" `venv`." +msgstr "" + +#: ../../tests/run-tests.md:242 +msgid "" +"For `conda` to work with `nox`, you will need to ensure that either " +"`conda` or `mamba` is installed on your computer." +msgstr "" + +#: ../../tests/run-tests.md:264 +msgid "To run the above session you'd use:" +msgstr "" + +#: ../../tests/test-types.md:1 +msgid "Test Types for Python packages" +msgstr "" + +#: ../../tests/test-types.md:3 +msgid "Three types of tests: Unit, Integration & Functional Tests" +msgstr "" + +#: ../../tests/test-types.md:5 +msgid "" +"There are different types of tests that you want to consider when " +"creating your test suite:" +msgstr "" + +#: ../../tests/test-types.md:8 +msgid "Unit tests" +msgstr "" + +#: ../../tests/test-types.md:9 +msgid "Integration" +msgstr "" + +#: ../../tests/test-types.md:10 +msgid "End-to-end (also known as Functional) tests" +msgstr "" + +#: ../../tests/test-types.md:12 +msgid "" +"Each type of test has a different purpose. Here, you will learn about all" +" three types of tests." +msgstr "" + +#: ../../tests/test-types.md:15 +msgid "" +"I think this page would be stronger if we did have some examples from our" +" package here: https://github.com/pyOpenSci/pyosPackage" +msgstr "" + +#: ../../tests/test-types.md:20 +msgid "Unit Tests" +msgstr "" + +#: ../../tests/test-types.md:22 +msgid "" +"A unit test involves testing individual components or units of code in " +"isolation to ensure that they work correctly. The goal of unit testing is" +" to verify that each part of the software, typically at the function or " +"method level, performs its intended task correctly." +msgstr "" + +#: ../../tests/test-types.md:24 +msgid "" +"Unit tests can be compared to examining each piece of your puzzle to " +"ensure parts of it are not broken. If all of the pieces of your puzzle " +"don’t fit together, you will never complete it. Similarly, when working " +"with code, tests ensure that each function, attribute, class, method " +"works properly when isolated." +msgstr "" + +#: ../../tests/test-types.md:26 +msgid "" +"**Unit test example:** Pretend that you have a function that converts a " +"temperature value from Celsius to Fahrenheit. A test for that function " +"might ensure that when provided with a value in Celsius, the function " +"returns the correct value in degrees Fahrenheit. That function is a unit " +"test. It checks a single unit (function) in your code." +msgstr "" + +#: ../../tests/test-types.md:44 +msgid "" +"Example unit test for the above function. You'd run this test using the " +"`pytest` command in your **tests/** directory." +msgstr "" + +#: ../../tests/test-types.md:65 ../../tests/test-types.md:115 +msgid "" +"image of puzzle pieces that all fit together nicely. The puzzle pieces " +"are colorful - purple, green and teal." +msgstr "" + +#: ../../tests/test-types.md:69 +msgid "" +"Your unit tests should ensure each part of your code works as expected on" +" its own." +msgstr "" + +#: ../../tests/test-types.md:72 +msgid "Integration tests" +msgstr "" + +#: ../../tests/test-types.md:74 +msgid "" +"Integration tests involve testing how parts of your package work together" +" or integrate. Integration tests can be compared to connecting a bunch of" +" puzzle pieces together to form a whole picture. Integration tests focus " +"on how different pieces of your code fit and work together." +msgstr "" + +#: ../../tests/test-types.md:76 +msgid "" +"For example, if you had a series of steps that collected temperature data" +" in a spreadsheet, converted it from degrees celsius to Fahrenheit and " +"then provided an average temperature for a particular time period. An " +"integration test would ensure that all parts of that workflow behaved as " +"expected." +msgstr "" + +#: ../../tests/test-types.md:107 +msgid "" +"image of two puzzle pieces with some missing parts. The puzzle pieces are" +" purple teal yellow and blue. The shapes of each piece don’t fit " +"together." +msgstr "" + +#: ../../tests/test-types.md:112 +msgid "" +"If puzzle pieces have missing ends, they can’t work together with other " +"elements in the puzzle. The same is true with individual functions, " +"methods and classes in your software. The code needs to work both " +"individually and together to perform certain sets of tasks." +msgstr "" + +#: ../../tests/test-types.md:120 +msgid "" +"Your integration tests should ensure that parts of your code that are " +"expected to work together, do so as expected." +msgstr "" + +#: ../../tests/test-types.md:124 +msgid "End-to-end (functional) tests" +msgstr "" + +#: ../../tests/test-types.md:126 +msgid "" +"End-to-end tests (also referred to as functional tests) in Python are " +"like comprehensive checklists for your software. They simulate real user " +"end-to-end workflows to make sure the code base supports real life " +"applications and use-cases from start to finish. These tests help catch " +"issues that might not show up in smaller tests and ensure your entire " +"application or program behaves correctly. Think of them as a way to give " +"your software a final check before it's put into action, making sure it's" +" ready to deliver a smooth experience to its users." +msgstr "" + +#: ../../tests/test-types.md:128 +msgid "Image of a completed puzzle showing a daisy" +msgstr "" + +#: ../../tests/test-types.md:133 +msgid "" +"End-to-end or functional tests represent an entire workflow that you " +"expect your package to support." +msgstr "" + +#: ../../tests/test-types.md:137 +msgid "" +"End-to-end test also test how a program runs from start to finish. A " +"tutorial that you add to your documentation that runs in CI in an " +"isolated environment is another example of an end-to-end test." +msgstr "" + +#: ../../tests/test-types.md:140 +msgid "" +"For scientific packages, creating short tutorials that highlight core " +"workflows that your package supports, that are run when your " +"documentation is built could also serve as end-to-end tests." +msgstr "" + +#: ../../tests/test-types.md:143 +msgid "Comparing unit, integration and end-to-end tests" +msgstr "" + +#: ../../tests/test-types.md:145 +msgid "" +"Unit tests, integration tests, and end-to-end tests have complementary " +"advantages and disadvantages. The fine-grained nature of unit tests make " +"them well-suited for isolating where errors are occurring. However, unit " +"tests are not useful for verifying that different sections of code work " +"together." +msgstr "" + +#: ../../tests/test-types.md:147 +msgid "" +"Integration and end-to-end tests verify that the different portions of " +"the program work together, but are less well-suited for isolating where " +"errors are occurring. For example, when you refactor your code, it is " +"possible that that your end-to-end tests will break. But if the refactor " +"didn't introduce new behavior to your existing code, then you can rely on" +" your unit tests to continue to pass, testing the original functionality " +"of your code." +msgstr "" + +#: ../../tests/test-types.md:152 +msgid "" +"It is important to note that you don't need to spend energy worrying " +"about the specifics surrounding the different types of tests. When you " +"begin to work on your test suite, consider what your package does and how" +" you may need to test parts of your package. Bring familiar with the " +"different types of tests can provides a framework to help you think about" +" writing tests and how different types of tests can complement each " +"other." +msgstr "" + +#: ../../tests/tests-ci.md:1 +msgid "Run tests with Continuous Integration" +msgstr "" + +#: ../../tests/tests-ci.md:3 +msgid "" +"Running your [test suite locally](run-tests) is useful as you develop " +"code and also test new features or changes to the code base. However, you" +" also will want to setup Continuous Integration (CI) to run your tests " +"online. CI allows you to run all of your tests in the cloud. While you " +"may only be able to run tests locally on a specific operating system, " +"using CI you can specify tests to run both on various versions of Python " +"and across different operating systems." +msgstr "" + +#: ../../tests/tests-ci.md:5 +msgid "" +"CI can also be triggered for pull requests and pushes to your repository." +" This means that every pull request that you, your maintainer team or a " +"contributor submit, can be tested. In the end CI testing ensures your " +"code continues to run as expected even as changes are made to the code " +"base." +msgstr "" + +#: ../../tests/tests-ci.md:9 +msgid "" +"Learn more about Continuous Integration and how it can be used, here. " +"(add link)" +msgstr "" + +#: ../../tests/tests-ci.md:13 +msgid "CI & pull requests" +msgstr "" + +#: ../../tests/tests-ci.md:15 +msgid "" +"CI is invaluable if you have outside people contributing to your " +"software. You can setup CI to run on all pull requests submitted to your " +"repository. CI can make your repository more friendly to new potential " +"contributors. It allows users to contribute code, documentation fixes and" +" more without having to create development environments, run tests and " +"build documentation locally." +msgstr "" + +#: ../../tests/tests-ci.md:22 +msgid "Example GitHub action that runs tests" +msgstr "" + +#: ../../tests/tests-ci.md:24 +msgid "" +"Below is an example GitHub action that runs tests using nox across both " +"Windows, Mac and Linux and on Python versions 3.9-3.11." +msgstr "" + +#: ../../tests/tests-ci.md:28 +msgid "" +"To work properly, this file should be located in a root directory of your" +" GitHub repository:" +msgstr "" + +#: ../../tests/write-tests.md:1 +msgid "Write tests for your Python package" +msgstr "" + +#: ../../tests/write-tests.md:3 +msgid "" +"Writing code that tests your package code, also known as test suites, is " +"important for you as a maintainer, your users, and package contributors. " +"Test suites consist of sets of functions, methods, and classes that are " +"written with the intention of making sure a specific part of your code " +"works as you expected it to." +msgstr "" + +#: ../../tests/write-tests.md:7 +msgid "Why write tests for your package?" +msgstr "" + +#: ../../tests/write-tests.md:9 +msgid "" +"Tests act as a safety net for code changes. They help you spot and " +"rectify bugs before they affect users. Tests also instill confidence that" +" code alterations from contributors won't breaking existing " +"functionality." +msgstr "" + +#: ../../tests/write-tests.md:13 +msgid "Writing tests for your Python package is important because:" +msgstr "" + +#: ../../tests/write-tests.md:15 +msgid "" +"**Catch Mistakes:** Tests are a safety net. When you make changes or add " +"new features to your package, tests can quickly tell you if you " +"accidentally broke something that was working fine before." +msgstr "" + +#: ../../tests/write-tests.md:16 +msgid "" +"**Save Time:** Imagine you have a magic button that can automatically " +"check if your package is still working properly. Tests are like that " +"magic button! They can run all those checks for you saving you time." +msgstr "" + +#: ../../tests/write-tests.md:17 +msgid "" +"**Easier Collaboration:** If you're working with others, or have outside " +"contributors, tests help everyone stay on the same page. Your tests " +"explain how your package is supposed to work, making it easier for others" +" to understand and contribute to your project." +msgstr "" + +#: ../../tests/write-tests.md:18 +msgid "" +"**Fearless Refactoring:** Refactoring means making improvements to your " +"code structure without changing its behavior. Tests empower you to make " +"these changes as if you break something, test failures will let you know." +msgstr "" + +#: ../../tests/write-tests.md:19 +msgid "" +"**Documentation:** Tests serve as technical examples of how to use your " +"package. This can be helpful for a new technical contributor that wants " +"to contribute code to your package. They can look at your tests to " +"understand how parts of your code functionality fits together." +msgstr "" + +#: ../../tests/write-tests.md:20 +msgid "" +"**Long-Term ease of maintenance:** As your package evolves, tests ensure " +"that your code continues to behave as expected, even as you make changes " +"over time. Thus you are helping your future self when writing tests." +msgstr "" + +#: ../../tests/write-tests.md:21 +msgid "" +"**Easier pull request reviews:** By running your tests in a CI framework " +"such as GitHub actions, each time you or a contributor makes a change to " +"your code-base, you can catch issues and things that may have changed in " +"your code base. This ensures that your software behaves the way you " +"expect it to." +msgstr "" + +#: ../../tests/write-tests.md:23 +msgid "Tests for user edge cases" +msgstr "" + +#: ../../tests/write-tests.md:25 +msgid "" +"Edge cases refer to unexpected or \"outlier\" ways that some users may " +"use your package. Tests enable you to address various edge cases that " +"could impair your package's functionality. For example, what occurs if a " +"function expects a pandas `dataframe` but a user supplies a numpy " +"`array`? Does your code gracefully handle this situation, providing clear" +" feedback, or does it leave users frustrated by an unexplained failure?" +msgstr "" + +#: ../../tests/write-tests.md:33 +msgid "" +"For a good introduction to testing, see [this Software Carpentry " +"lesson](https://swcarpentry.github.io/python-novice-" +"inflammation/10-defensive.html)" +msgstr "" + +#: ../../tests/write-tests.md:41 +msgid "" +"Imagine you're working on a puzzle where each puzzle piece represents a " +"function, method, class or attribute in your Python package that you want" +" other people to be able to use. Would you want to give someone a puzzle " +"that has missing pieces or pieces that don't fit together? Providing " +"people with the right puzzle pieces that work together can be compared to" +" writing tests for your Python package." +msgstr "" + +#: ../../tests/write-tests.md:44 +msgid "Test examples" +msgstr "" + +#: ../../tests/write-tests.md:47 +msgid "" +"Let’s say you have a Python function that adds two numbers a and b " +"together." +msgstr "" + +#: ../../tests/write-tests.md:54 +msgid "" +"A test to ensure that function runs as you might expect when provided " +"with different numbers might look like this:" +msgstr "" + +#: ../../tests/write-tests.md:72 +msgid "🧩🐍" +msgstr "" + +#: ../../tests/write-tests.md:74 +msgid "How do I know what type of tests to write?" +msgstr "" + +#: ../../tests/write-tests.md:77 +msgid "" +"This section has been adapted from [a presentation by Nick " +"Murphy](https://zenodo.org/record/8185113)." +msgstr "" + +#: ../../tests/write-tests.md:80 +msgid "" +"At this point, you may be wondering - what should you be testing in your " +"package? Below are a few examples:" +msgstr "" + +#: ../../tests/write-tests.md:82 +msgid "" +"**Test some typical cases:** Test that the package functions as you " +"expect it to when users use it. For instance, if your package is supposed" +" to add two numbers, test that the outcome value of adding those two " +"numbers is correct." +msgstr "" + +#: ../../tests/write-tests.md:84 +msgid "" +"**Test special cases:** Sometimes there are special or outlier cases. For" +" instance, if a function performs a specific calculation that may become " +"problematic closer to the value = 0, test it with the input of both 0 and" +msgstr "" + +#: ../../tests/write-tests.md:86 +msgid "" +"**Test at and near the expected boundaries:** If a function requires a " +"value that is greater than or equal to 1, make sure that the function " +"still works with both the values 1 and less than one and 1.001 as well " +"(something close to the constraint value).." +msgstr "" + +#: ../../tests/write-tests.md:88 +msgid "" +"**Test that code fails correctly:** If a function requires a value " +"greater than or equal to 1, then test at 0.999. Make sure that the " +"function fails gracefully when given unexpected values and help and that " +"the user can easily understand why if failed (provides a useful error " +"message)." +msgstr "" + diff --git a/locales/ja/LC_MESSAGES/tutorials.po b/locales/ja/LC_MESSAGES/tutorials.po new file mode 100644 index 00000000..6f88c534 --- /dev/null +++ b/locales/ja/LC_MESSAGES/tutorials.po @@ -0,0 +1,5537 @@ +# 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-08-02 18:04+0900\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: ja\n" +"Language-Team: ja \n" +"Plural-Forms: nplurals=1; plural=0;\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 +msgid "Get to Know Hatch" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:3 +msgid "" +"Our Python packaging tutorials use the tool " +"[Hatch](https://hatch.pypa.io/latest/). While there are [many great " +"packaging tools](/package-structure-code/python-package-build-tools) out " +"there, we have selected Hatch because:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:8 +msgid "" +"It is an end-to-end tool that supports most of the steps required to " +"create a quality Python package. Beginners will have fewer tools to learn" +" if they use Hatch." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:11 +msgid "" +"It supports different build back-ends if you ever need to compile code in" +" other languages." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:13 +msgid "" +"As a community, pyOpenSci has decided that Hatch is a user-friendly tool " +"that supports many different scientific Python use cases." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:16 +msgid "" +"In this tutorial, you will install and get to know Hatch a bit more " +"before starting to use it." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:19 +msgid "You need two things to successfully complete this tutorial:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:21 +msgid "You need Python installed." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:22 +msgid "You need Hatch installed." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:25 +msgid "" +"If you don't already have Python installed on your computer, Hatch will " +"do it for you when you install Hatch." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:29 +msgid "Install Hatch" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:31 +msgid "" +"To begin, follow the operating-system-specific instructions below to " +"install Hatch." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md +msgid "MAC" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:38 +msgid "" +"Follow the instructions " +"[here](https://hatch.pypa.io/latest/install/#installers)." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:40 +msgid "" +"Download the latest GUI installer for MAC [hatch-" +"universal.pkg](https://github.com/pypa/hatch/releases/latest/download" +"/hatch-universal.pkg)." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:41 +msgid "Run the installer and follow the setup instructions." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:42 +msgid "If your terminal is open, then restart it." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md +msgid "Windows" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:48 +msgid "" +"In your browser, download the correct `.msi` file for your system: " +"[hatch-x64.msi](https://github.com/pypa/hatch/releases/latest/download/hatch-x64.msi)" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:50 +msgid "Run your downloaded installer file and follow the on-screen instructions." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md +msgid "Linux" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:56 +msgid "" +"We suggest that you install Hatch using pipx on Linux. however, if you " +"prefer another method, check out the [Hatch installation " +"documentation](https://hatch.pypa.io/latest/install/) for other methods." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:70 +msgid "" +"Hatch can also be installed directly using " +"[pip](https://hatch.pypa.io/latest/install/#pip) or " +"[conda](https://hatch.pypa.io/latest/install/#conda). We encourage you to" +" follow the instructions above because we have found that the Hatch " +"installers for Windows and Mac are the easiest and most efficient." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:74 +msgid "" +"Our Linux users have found success installing Hatch with pipx if they " +"already use apt install." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:77 +msgid "" +"Both approaches (using a graphical installer on Windows/Mac and pipx) " +"ensure that you have Hatch installed globally. A global install means " +"that Hatch is available across all of your Python environments on your " +"computer." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:82 +msgid "Check that hatch installed correctly" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:84 +msgid "" +"Once you have completed the installation instructions above, you can open" +" your terminal, and make sure that Hatch installed correctly using the " +"command below:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:92 +msgid "" +"*Note the version number output of `hatch --version` will likely be " +"different from the output above in this tutorial.*" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:95 +msgid "Configure Hatch" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:97 +msgid "" +"Once you have installed Hatch, you can customize its configuration. This " +"includes setting the default name and setup for every package you create." +" While this step is not required, we suggest that you do it." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:101 +msgid "" +"Hatch stores your configuration in a [`config.toml` " +"file](https://hatch.pypa.io/latest/config/project-templates/)." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:103 +msgid "" +"While you can update the `config.toml` file through the command line, it " +"might be easier to look at and update it in a text editor if you are " +"using it for the first time." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:107 +msgid "Step 1: Open and Edit Your `config.toml` File" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:109 +msgid "" +"To open the config file in your file browser, run the following command " +"in your shell:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:112 +msgid "`hatch config explore`" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:114 +msgid "" +"This will open up a directory window that allows you to double-click on " +"the file and open it in your favorite text editor." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:117 +msgid "" +"You can also retrieve the location of the Hatch config file by running " +"the following command in your shell:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:125 +msgid "Step 2 - update your email and name" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:127 +msgid "" +"Once the file is open, update the [template] table of the `config.toml` " +"file with your name and email. This information will be used in any " +"`pyproject.toml` metadata files that you create using Hatch." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:137 +msgid "Step 3" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:139 +msgid "Next, set tests to false in the `[template.plugins.default]` table." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:141 +msgid "" +"While tests are important, setting the tests configuration in Hatch to " +"`true` will create a more complex `pyproject.toml` file. You won't need " +"to use this feature in this beginner friendly tutorial series but we will" +" introduce it in later tutorials." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:146 +msgid "Your `config.toml` file should look something like the one below." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:184 +msgid "" +"Also notice that the default license option is MIT. While we will discuss" +" license in more detail in a later lesson, the MIT license is the " +"recommended permissive license from " +"[choosealicense.com](https://www.choosealicense.com) and as such we will " +"use it for this tutorial series." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:190 +msgid "You are of course welcome to select another license." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:192 +#: ../../tutorials/installable-code.md:22 +#: ../../tutorials/installable-code.md:411 +#: ../../tutorials/installable-code.md:502 ../../tutorials/intro.md: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:193 +msgid "" +"I think we'd need the SPDX license options here if they want to chose " +"bsd-3 for instance" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:196 +msgid "Step 4: Close the config file and run `hatch config show`" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:198 +msgid "" +"Once you have completed the steps above run the following command in your" +" shell." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:200 +msgid "`hatch config show`" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:202 +msgid "" +"`hatch config show` will print out the contents of your `config.toml` " +"file in your shell. look at the values and ensure that your name, email " +"is set. Also make sure that `tests=false`." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:206 +msgid "Hatch features" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:208 +msgid "" +"Hatch offers a suite of features that will make creating, publishing and " +"maintaining your Python package easier." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:211 +msgid "Comparison to other tools" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:213 +msgid "" +"[We compared Hatch to several of the other popular packaging tools in the" +" ecosystem including flit, pdm and poetry. Learn more here](package-" +"features)" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:216 +msgid "[More on Hatch here](hatch)" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:218 +msgid "A few features that Hatch offers" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:220 +msgid "" +"it will convert metadata stored in a `setup.py` or `setup.cfg` file to a " +"pyproject.toml file for you (see [Migrating setup.py to pyproject.toml " +"using Hatch](setup-py-to-pyproject-toml.md ))" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:222 +msgid "" +"It will help you by storing configuration information for publishing to " +"PyPI after you've entered it once." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:224 +msgid "Use `hatch -h` to see all of the available commands." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:226 +msgid "What's next" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:228 +msgid "" +"In the next lesson you'll learn how to package and make your code " +"installable using Hatch." +msgstr "" + +#: ../../tutorials/installable-code.md:6 +msgid "Make your Python code installable" +msgstr "" + +#: ../../tutorials/installable-code.md:8 +msgid "What we previously covered" +msgstr "" + +#: ../../tutorials/installable-code.md:9 +msgid "" +"[In the previous lesson](intro), you learned about what a Python package " +"is. You also learned about the [benefits of creating a Python package" +"](package-benefits)." +msgstr "" + +#: ../../tutorials/installable-code.md:13 +msgid "" +"Your next step in our packaging tutorial series is to create a Python " +"package that is installable both locally and remotely from a website such" +" as GitHub (or GitLab). The package that you create in this lesson will " +"have the bare minimum elements needed to be installable into a Python " +"environment." +msgstr "" + +#: ../../tutorials/installable-code.md:18 +msgid "" +"Making your code installable is an important steps towards creating a " +"full Python package that is directly installable from PyPI." +msgstr "" + +#: ../../tutorials/installable-code.md:23 +msgid "" +"Is it clear where to add commands? Bash vs. Python console Bash vs. Zsh " +"is different" +msgstr "" + +#: ../../tutorials/installable-code.md:25 +msgid "Does this lesson run as expected on windows and mac?" +msgstr "" + +#: ../../tutorials/installable-code.md:26 +msgid "" +"ADD: note about what makes something \"package worthy\", with a common " +"misconception being that a package should be production-ready code that's" +" valuable to a broad audience. this may not be a pervasive misconception " +"in Python, but a quick break-out with an explanation of what a package " +"can consist of would be helpful." +msgstr "" + +#: ../../tutorials/installable-code.md:31 +msgid "" +"Diagram showing the basic steps to creating an installable package. There" +" are 4 boxes with arrows pointing towards the right. The boxes read, your" +" code, create package structure, add metadata to pyproject.toml and pip " +"install package." +msgstr "" + +#: ../../tutorials/installable-code.md:33 +msgid "" +"A basic installable package needs a few things: code, a [specific package" +" file structure](https://www.pyopensci.org/python-package-guide/package-" +"structure-code/python-package-structure.html) and a `pyproject.toml` " +"containing your package's name and version. Once you have these items in " +"the correct directory structure, you can pip install your package into " +"any environment on your computer. You will learn how to create a basic " +"installable package in this lesson." +msgstr "" + +#: ../../tutorials/installable-code.md:37 +msgid "About this lesson" +msgstr "" + +#: ../../tutorials/installable-code.md:43 +msgid "" +"How to make your code installable into any Python environment both " +"locally and from GitHub" +msgstr "" + +#: ../../tutorials/installable-code.md:44 +msgid "" +"How to create a basic `pyproject.toml` file that includes package " +"dependencies and metadata. This file is required to make your package " +"installable." +msgstr "" + +#: ../../tutorials/installable-code.md:45 +msgid "" +"How to declare a [build backend](build_backends) which will be used to " +"[build](build-package) and install your package" +msgstr "" + +#: ../../tutorials/installable-code.md:46 +msgid "How to install your package in editable mode for interactive development" +msgstr "" + +#: ../../tutorials/installable-code.md:48 +msgid "**What you need to complete this lesson**" +msgstr "" + +#: ../../tutorials/installable-code.md:50 +msgid "" +"To complete this lesson you will need a local Python environment and " +"shell on your computer. You will also need to have [Hatch installed](get-" +"to-know-hatch)." +msgstr "" + +#: ../../tutorials/installable-code.md:53 +msgid "" +"If you are using Windows or are not familiar with Shell, you may want to " +"check out the Carpentries shell lesson[^shell-lesson]. Windows users will" +" likely need to configure a tool for any Shell and git related steps." +msgstr "" + +#: ../../tutorials/installable-code.md:55 +msgid "**What comes next**" +msgstr "" + +#: ../../tutorials/installable-code.md:57 +msgid "In the upcoming lessons you will learn how to:" +msgstr "" + +#: ../../tutorials/installable-code.md:59 +msgid "[Publish your package to PyPI](publish-pypi)" +msgstr "" + +#: ../../tutorials/installable-code.md:60 +msgid "Add a README file to your package to support community use" +msgstr "" + +#: ../../tutorials/installable-code.md:61 +msgid "" +"Add additional project metadata to your package to support PyPI " +"publication" +msgstr "" + +#: ../../tutorials/installable-code.md:67 +msgid "" +"This diagram has two smaller boxes with arrows pointing to the right to a" +" Python environment. The small boxes read your-package and pip install " +"package. The environment box on the right reads - your Python " +"environment. It them lists your-package along with a few other core " +"packages such as Matplotlib, NumPy, Pandas, Xarray and GeoPandas." +msgstr "" + +#: ../../tutorials/installable-code.md:69 +msgid "" +"Making your code installable is the first step towards creating a " +"publishable Python package. Once your code is installable, it is a Python" +" package and can be added to any Python environment on your computer and " +"imported in the same way that you might import a package such as Pandas " +"or GeoPandas. If your code is on GitHub or GitLab you can also install it" +" directly from there." +msgstr "" + +#: ../../tutorials/installable-code.md:74 +msgid "About the Python package directory structure" +msgstr "" + +#: ../../tutorials/installable-code.md:76 +msgid "" +"To make your Python code installable you need to create a specific " +"directory structure with the following elements:" +msgstr "" + +#: ../../tutorials/installable-code.md:78 +msgid "A `pyproject.toml` file." +msgstr "" + +#: ../../tutorials/installable-code.md:79 +msgid "A specific directory structure." +msgstr "" + +#: ../../tutorials/installable-code.md:80 +msgid "Some code." +msgstr "" + +#: ../../tutorials/installable-code.md:81 +msgid "An `__init__.py` file in your code directory." +msgstr "" + +#: ../../tutorials/installable-code.md:83 +msgid "The directory structure you’ll create in this lesson will look like this:" +msgstr "" + +#: ../../tutorials/installable-code.md:95 +msgid "About the basic package directory structure" +msgstr "" + +#: ../../tutorials/installable-code.md:97 +msgid "Notice a few things about the above layout:" +msgstr "" + +#: ../../tutorials/installable-code.md:99 +msgid "" +"Your package code lives within a `src/packagename` directory. We suggest " +"that you use `src` (short for **source code**) directory as it [ensures " +"that you are running tests on the installed version of your " +"code](https://www.pyopensci.org/python-package-guide/package-structure-" +"code/python-package-structure.html#the-src-layout-and-testing)." +msgstr "" + +#: ../../tutorials/installable-code.md:100 +msgid "" +"Within the `src` directory you have a package directory called " +"`pyospackage`. Use the name of your package for that directory name. This" +" will be the name for importing your package in Python code once " +"installed." +msgstr "" + +#: ../../tutorials/installable-code.md:101 +msgid "" +"In your package directory, you have an `__init__.py` file and all of your" +" Python modules. You will learn more about the `__init__.py` file below." +msgstr "" + +#: ../../tutorials/installable-code.md:102 +msgid "The `pyproject.toml` file lives at the root directory of your package." +msgstr "" + +#: ../../tutorials/installable-code.md:103 +msgid "" +"The name of the root directory for the package is **pyospackage** which " +"is the name of the package. This is not a requirement but you will often " +"see that the GitHub / GitLab repository and the root directory name are " +"the same as the package name." +msgstr "" + +#: ../../tutorials/installable-code.md:105 +msgid "What is an `__init__.py` file?" +msgstr "" + +#: ../../tutorials/installable-code.md:107 +msgid "" +"The `__init__.py` file tells Python that a directory should be treated as" +" a Python package. As such, a directory with an `__init__.py` file can be" +" imported directly into Python. The `__init__.py` file does not need to " +"contain any code in order for Python to recognize it; it can be empty." +msgstr "" + +#: ../../tutorials/installable-code.md:111 +msgid "" +"For example, following the file structure example above which has an " +"`__init__.py` file within it, you can run:" +msgstr "" + +#: ../../tutorials/installable-code.md:117 ../../tutorials/pyproject-toml.md:48 +msgid "What is a pyproject.toml file?" +msgstr "" + +#: ../../tutorials/installable-code.md:119 +msgid "The **pyproject.toml** file is:" +msgstr "" + +#: ../../tutorials/installable-code.md:121 +msgid "" +"Where you define your project’s metadata (including its name, authors, " +"license, etc)" +msgstr "" + +#: ../../tutorials/installable-code.md:122 +msgid "Where you define dependencies (the packages that it depends on)" +msgstr "" + +#: ../../tutorials/installable-code.md:123 +msgid "" +"Used to specify and configure what build backend you want to use to " +"[build your package](../package-structure-code/python-package-" +"distribution-files-sdist-wheel)." +msgstr "" + +#: ../../tutorials/installable-code.md:125 +msgid "" +"After the `__init__.py` and `pyproject.toml` files have been added, your " +"package can be built and distributed as an installable Python package " +"using tools such as pip. Note that the `pyproject.toml` file needs to " +"have a few basic items defined for the package to be installable " +"including:" +msgstr "" + +#: ../../tutorials/installable-code.md:131 +msgid "The `build-backend` that you want to use," +msgstr "" + +#: ../../tutorials/installable-code.md:132 +msgid "The project `name` and `version`." +msgstr "" + +#: ../../tutorials/installable-code.md:134 +msgid "Why the pyproject.toml file is important" +msgstr "" + +#: ../../tutorials/installable-code.md:138 +msgid "" +"The `pyproject.toml` file replaces some of the functionality of both the " +"`setup.py` file and `setup.cfg` files. If you try to pip install a " +"package with no `pyproject.toml` you will get the following error:" +msgstr "" + +#: ../../tutorials/installable-code.md:150 +msgid "Note about `setup.py`" +msgstr "" + +#: ../../tutorials/installable-code.md:154 +msgid "" +"If your project already defines a `setup.py` file, Hatch can be used to " +"automatically create the `pyproject.toml`." +msgstr "" + +#: ../../tutorials/installable-code.md:155 +msgid "" +"See [Using Hatch to Migrate setup.py to a pyproject.toml ](setup-py-to-" +"pyproject-toml.md)" +msgstr "" + +#: ../../tutorials/installable-code.md:161 +msgid "Time to create your Python package!" +msgstr "" + +#: ../../tutorials/installable-code.md:163 +msgid "" +"Now that you understand the basics of the Python package directory " +"structure, and associated key files (`__init__.py` and `pyproject.toml`)," +" it's time to create your Python package! Below you will create a " +"directory structure similar to the structure described above using Hatch." +msgstr "" + +#: ../../tutorials/installable-code.md:167 +msgid "Step 1: Set Up the Package Directory Structure" +msgstr "" + +#: ../../tutorials/installable-code.md:169 +msgid "Open your shell or preferred terminal." +msgstr "" + +#: ../../tutorials/installable-code.md:170 +msgid "" +"Use the shell `cd` command to navigate in your shell to the location " +"where you'd like your package directory to live. Hatch will create the " +"package directory for you" +msgstr "" + +#: ../../tutorials/installable-code.md:171 +msgid "Choose a name for your package. The name should:" +msgstr "" + +#: ../../tutorials/installable-code.md:172 +msgid "Have no spaces (*Required*)" +msgstr "" + +#: ../../tutorials/installable-code.md:173 +msgid "" +"Use all lowercase characters (*Recommended*). For this tutorial we will " +"use `pyospackage`." +msgstr "" + +#: ../../tutorials/installable-code.md:174 +msgid "" +"Only use letter and the characters _ or - in the name. This means that " +"the name `pyos*package` is not an acceptable name. However, the names " +"`pyos_package` or `pyos-package` both are ok" +msgstr "" + +#: ../../tutorials/installable-code.md:176 +msgid "Hatch and project names" +msgstr "" + +#: ../../tutorials/installable-code.md:177 +msgid "" +"Hatch makes some decisions for your project's name when you run `hatch " +"new`" +msgstr "" + +#: ../../tutorials/installable-code.md:179 +msgid "These include using:" +msgstr "" + +#: ../../tutorials/installable-code.md:180 +msgid "dashes for the top level directory" +msgstr "" + +#: ../../tutorials/installable-code.md:181 +msgid "dashes for the project name in the pyproject.toml" +msgstr "" + +#: ../../tutorials/installable-code.md:182 +msgid "underscores for the package directory name" +msgstr "" + +#: ../../tutorials/installable-code.md:196 +msgid "If you use a name with underscores, Hatch will return the same thing:" +msgstr "" + +#: ../../tutorials/installable-code.md:209 +msgid "" +"In both of the examples above the project name in the pyproject.toml file" +" that hatch creates is `pyos-package`." +msgstr "" + +#: ../../tutorials/installable-code.md:213 +msgid "Next run:" +msgstr "" + +#: ../../tutorials/installable-code.md:228 +msgid "Your final project directory structure should look like this:" +msgstr "" + +#: ../../tutorials/installable-code.md:243 +msgid "Step 2: Add module to your package" +msgstr "" + +#: ../../tutorials/installable-code.md:245 +msgid "" +"A Python module refers to a `.py` file containing the code that you want " +"your package to access and run. Within the `pyospackage` subdirectory, " +"add at least one Python modules (.py files)." +msgstr "" + +#: ../../tutorials/installable-code.md:247 +msgid "" +"If you don't have code already and are just learning how to create a " +"Python package, then create an empty `add_numbers.py` file. You will " +"populate the `add_numbers.py` file with code provided below." +msgstr "" + +#: ../../tutorials/installable-code.md:250 +msgid "Python modules and the `__init__.py` file" +msgstr "" + +#: ../../tutorials/installable-code.md:254 +msgid "" +"When you see the word module, we are referring to a `.py` file containing" +" Python code." +msgstr "" + +#: ../../tutorials/installable-code.md:257 +msgid "" +"The `__init__.py` allows Python to recognize that a directory contains " +"at least one module that may be imported and used in your code. A package" +" can have multiple modules[^python-modules]." +msgstr "" + +#: ../../tutorials/installable-code.md:261 +msgid "Your project directory should now look like this:" +msgstr "" + +#: ../../tutorials/installable-code.md:271 +msgid "Step 3: Add code to your module" +msgstr "" + +#: ../../tutorials/installable-code.md:273 +msgid "" +"If you are following along and making a Python package from scratch then " +"you can add the code below to your `add_numbers.py` module. The function " +"below adds two integers together and returns the result. Notice that the " +"code below has a few features that we will review in future tutorials:" +msgstr "" + +#: ../../tutorials/installable-code.md:275 +msgid "It has a [numpy-style docstring](numpy-docstring)" +msgstr "" + +#: ../../tutorials/installable-code.md:276 +msgid "It uses [typing](type-hints)" +msgstr "" + +#: ../../tutorials/installable-code.md:278 +msgid "" +"Python can support many different docstrings formats depending on the " +"documentation build system you wish to use. The most popular supported " +"formats for documenting Python objects are NumPy Style " +"Docstring[^numpydoc], Google Style Docstring[^googledoc], and the Epytext" +" Style Docstrings[^epytextdoc]." +msgstr "" + +#: ../../tutorials/installable-code.md:280 +msgid "**pyOpenSci recommends using the NumPy Docstring convention.**" +msgstr "" + +#: ../../tutorials/installable-code.md:282 +msgid "" +"If you aren’t familiar with docstrings or typing yet, that is ok. You can" +" review [this page in the pyOpenSci packaging " +"guide](https://www.pyopensci.org/python-package-guide/documentation" +"/write-user-documentation/document-your-code-api-docstrings.html) for an " +"overview of both topics." +msgstr "" + +#: ../../tutorials/installable-code.md:311 +msgid "Step 4: Modify metadata in your `pyproject.toml` file" +msgstr "" + +#: ../../tutorials/installable-code.md:313 +msgid "" +"Next, you will modify some of the metadata (information) that Hatch adds " +"to your `pyproject.toml` file. You are are welcome to copy the file we " +"have in our [example pyospackage GitHub " +"repository](https://github.com/pyOpenSci/pyosPackage)." +msgstr "" + +#: ../../tutorials/installable-code.md:317 +msgid "Brief overview of the TOML file" +msgstr "" + +#: ../../tutorials/installable-code.md:320 +msgid "" +"[The TOML format](https://toml.io/en/) consists of tables and variables. " +"Tables are sections of information denoted by square brackets:" +msgstr "" + +#: ../../tutorials/installable-code.md:322 +msgid "`[this-is-a-table]`." +msgstr "" + +#: ../../tutorials/installable-code.md:324 +msgid "" +"Tables can contain variables within them defined by an variable name and " +"an `=` sign. For instance, a `build-system` table most often holds two " +"(2) variables:" +msgstr "" + +#: ../../tutorials/installable-code.md:327 +msgid "" +"`requires = `, which tells a build tool what tools it needs to install " +"prior to building your package. In this case " +"[hatchling](https://pypi.org/project/hatchling/)" +msgstr "" + +#: ../../tutorials/installable-code.md:329 +msgid "" +"`build-backend = `, which is used to define the specific build-backend " +"name, (in this example we are using `hatchling.build`)." +msgstr "" + +#: ../../tutorials/installable-code.md:338 +msgid "" +"TOML organizes data structures, defining relationships within a " +"configuration file." +msgstr "" + +#: ../../tutorials/installable-code.md:341 +msgid "" +"[Learn more about the pyproject.toml format here.](../package-structure-" +"code/pyproject-toml-python-package-metadata)" +msgstr "" + +#: ../../tutorials/installable-code.md:345 +msgid "" +"You will learn more about the `pyproject.toml` format in the [next lesson" +" when you add additional metadata / information to this file.](pyproject-" +"toml.md)" +msgstr "" + +#: ../../tutorials/installable-code.md:348 +msgid "" +"Open up the `pyproject.toml` file that Hatch created in your favorite " +"text editor. It should look something like the example below." +msgstr "" + +#: ../../tutorials/installable-code.md:390 +msgid "Edit the file as follows:" +msgstr "" + +#: ../../tutorials/installable-code.md:392 +msgid "" +"Delete `dynamic = [\"version\"]`: This sets up dynamic versioning based " +"on tags stored in your git commit history. We will walk through " +"implementing this in a later lesson." +msgstr "" + +#: ../../tutorials/installable-code.md:393 +msgid "" +"Add `version = \"0.1\"` in the place of `dynamic = [\"version\"]` which " +"you just deleted. This sets up manual versioning." +msgstr "" + +#: ../../tutorials/installable-code.md:394 +msgid "Fill in the description if it doesn't already exist." +msgstr "" + +#: ../../tutorials/installable-code.md:404 +msgid "Remove the `[tool.hatch.version]` table from the bottom of the file." +msgstr "" + +#: ../../tutorials/installable-code.md:412 +msgid "" +"When this lesson exists, uncomment this admonition You will learn how to " +"automate defining a package version using git tags in the version and " +"release your package lesson." +msgstr "" + +#: ../../tutorials/installable-code.md:417 +msgid "OPTIONAL: Adjust project classifiers" +msgstr "" + +#: ../../tutorials/installable-code.md:419 +msgid "" +"Hatch by default provides a list of classifiers that define what Python " +"versions your package supports. These classifiers do not in any way " +"impact your package's build and are primarily intended to be used when " +"you publish your package to PyPI." +msgstr "" + +#: ../../tutorials/installable-code.md:424 +msgid "" +"If you don't plan on publishing to PyPI, you can skip this section. " +"However, if you wish, you can clean it up a bit." +msgstr "" + +#: ../../tutorials/installable-code.md:427 +msgid "To begin:" +msgstr "" + +#: ../../tutorials/installable-code.md:429 +msgid "Remove support for Python 3.8" +msgstr "" + +#: ../../tutorials/installable-code.md:430 +msgid "" +"Within the `[project]` table, update `requires-python = \">3.8\"` to " +"`requires-python = \">3.9\"`" +msgstr "" + +#: ../../tutorials/installable-code.md:432 +msgid "" +"Since you are creating a pure Python package in this lesson, you can " +"remove the following classifiers:" +msgstr "" + +#: ../../tutorials/installable-code.md:442 +msgid "Your new pyproject.toml file should now look something like this:" +msgstr "" + +#: ../../tutorials/installable-code.md:477 +msgid "The bare minimum needed in a pyproject.toml file" +msgstr "" + +#: ../../tutorials/installable-code.md:480 +msgid "" +"The core information that you need in a `pyproject.toml` file in order to" +" publish on PyPI is your **package's name** and the **version**. " +"However, we suggest that you flesh out your metadata early on in the " +"`pyproject.toml` file." +msgstr "" + +#: ../../tutorials/installable-code.md:482 +msgid "" +"Once you have your project metadata in the pyproject.toml file, you will " +"rarely update it. In the next lesson you’ll add more metadata and " +"structure to this file." +msgstr "" + +#: ../../tutorials/installable-code.md:486 +msgid "Step 5: Install your package locally" +msgstr "" + +#: ../../tutorials/installable-code.md:488 +msgid "At this point you should have:" +msgstr "" + +#: ../../tutorials/installable-code.md:490 +msgid "A project directory structure with a `pyproject.toml` file at the root" +msgstr "" + +#: ../../tutorials/installable-code.md:491 +msgid "A package directory containing an empty `__init__.py` file and" +msgstr "" + +#: ../../tutorials/installable-code.md:492 +msgid "At least one Python module (e.g. `add_numbers.py`)" +msgstr "" + +#: ../../tutorials/installable-code.md:494 +msgid "You are now ready to install (and build) your Python package!" +msgstr "" + +#: ../../tutorials/installable-code.md:496 +msgid "" +"While you can do this using hatch, we are going to use pip for this " +"lesson, so you can see how to install your tool into your preferred " +"environment." +msgstr "" + +#: ../../tutorials/installable-code.md:498 +msgid "" +"First open your preferred shell (Windows users may be using something " +"like gitbash) and `cd` into your project directory if you are not already" +" there." +msgstr "" + +#: ../../tutorials/installable-code.md:499 +msgid "Activate the Python environment that you wish to use." +msgstr "" + +#: ../../tutorials/installable-code.md:500 +msgid "Run `python -m pip install -e .`" +msgstr "" + +#: ../../tutorials/installable-code.md:503 +msgid "Add this back in when the lesson is published" +msgstr "" + +#: ../../tutorials/installable-code.md:504 +msgid "" +"Activate the Python environment that you wish to use. If you need help " +"with working with virtual environments check out this lesson (add link)." +msgstr "" + +#: ../../tutorials/installable-code.md:530 +msgid "What does `python -m pip install -e .` do?" +msgstr "" + +#: ../../tutorials/installable-code.md:533 +msgid "Let's break down `python -m pip install -e .`" +msgstr "" + +#: ../../tutorials/installable-code.md:535 +msgid "" +"`python -m pip install -e .` installs your package into the current " +"active Python environment in **editable mode** (`-e`). Installing your " +"package in editable mode, allows you to work on your code and then test " +"the updates interactively in your favorite Python interface. One " +"important caveat of editable mode is that every time you update your " +"code, you may need to restart Python." +msgstr "" + +#: ../../tutorials/installable-code.md:540 +msgid "" +"If you wish to install the package regularly (not in editable mode) you " +"can use:" +msgstr "" + +#: ../../tutorials/installable-code.md:543 +msgid "`python -m pip install . `" +msgstr "" + +#: ../../tutorials/installable-code.md:545 +msgid "**Using `python -m` when calling `pip`**" +msgstr "" + +#: ../../tutorials/installable-code.md:547 +msgid "" +"Above, you use`python -m` to call the version of pip installed into your " +"current active environment. `python -m` is important to ensure that you " +"are calling the version of pip installed in your current environment." +msgstr "" + +#: ../../tutorials/installable-code.md:552 +msgid "Look for pyospackage in your environment" +msgstr "" + +#: ../../tutorials/installable-code.md:554 +msgid "" +"Once you have installed your package, you can view it in your current " +"environment. If you are using `venv` or `conda`, `pip` list will allow " +"you to see your current package installations." +msgstr "" + +#: ../../tutorials/installable-code.md:558 +msgid "" +"Note that because pyospackage is installed in editable mode (`-e`) pip " +"will show you the directory path to your project's code" +msgstr "" + +#: ../../tutorials/installable-code.md:586 +msgid "Step 6: Test out your new package" +msgstr "" + +#: ../../tutorials/installable-code.md:588 +msgid "" +"After installing your package, type “python” at the command prompt in " +"your chosen terminal to start a Python session in your active Python " +"environment." +msgstr "" + +#: ../../tutorials/installable-code.md:591 +msgid "You can now import your package and access the `add_num` function." +msgstr "" + +#: ../../tutorials/installable-code.md:603 +msgid "Installing packages from GitHub" +msgstr "" + +#: ../../tutorials/installable-code.md:605 +msgid "" +"If you wish to share your code without publishing to PyPI you can always " +"install packages directly from GitHub using the syntax:" +msgstr "" + +#: ../../tutorials/installable-code.md:612 +msgid "To make your package GitHub installable, you can:" +msgstr "" + +#: ../../tutorials/installable-code.md:614 +msgid "Create a new GitHub repository" +msgstr "" + +#: ../../tutorials/installable-code.md:615 +msgid "" +"Push the contents of the project directory that you created above, to " +"GitHub" +msgstr "" + +#: ../../tutorials/installable-code.md:616 +msgid "" +"Finally install the package from GitHub using the command above. When you" +" use the command above, don't forget to substitute the user, repo, and " +"branch_or_tag with your specific values." +msgstr "" + +#: ../../tutorials/installable-code.md:618 +msgid "" +"For instance below you install the pyospackage from the main branch of " +"the pyOpenSci repository." +msgstr "" + +#: ../../tutorials/installable-code.md:621 +msgid "`python -m pip install git+https://github.com/user/repo.git@branch_or_tag`" +msgstr "" + +#: ../../tutorials/installable-code.md:625 +msgid "Congratulations! You created your first Python package" +msgstr "" + +#: ../../tutorials/installable-code.md:627 +msgid "" +"You did it! You have now created a Python package that you can install " +"into any Python environment." +msgstr "" + +#: ../../tutorials/installable-code.md:630 +msgid "In the upcoming lessons you will:" +msgstr "" + +#: ../../tutorials/installable-code.md:632 +msgid "" +"Learn how to [build and publish your Python package to (test) PyPI" +"](publish-pypi)" +msgstr "" + +#: ../../tutorials/installable-code.md:633 +msgid "Add a README file and LICENSE to your package" +msgstr "" + +#: ../../tutorials/installable-code.md:634 +msgid "" +"Add more metadata to your `pyproject.toml` file to support PyPI " +"publication." +msgstr "" + +#: ../../tutorials/installable-code.md:635 +msgid "learn how to publish to **conda-forge** from **PyPI**." +msgstr "" + +#: ../../tutorials/installable-code.md:637 +msgid "" +"Add a [README file](add-readme.md) and [LICENSE](add-license-coc.md) to " +"your package" +msgstr "" + +#: ../../tutorials/installable-code.md:638 +msgid "" +"[Add more metadata to your `pyproject.toml`](pyproject-toml.md) file to " +"support PyPI publication." +msgstr "" + +#: ../../tutorials/installable-code.md:639 +msgid "" +"[Learn how to build your package distribution](publish-pypi) files " +"(**sdist** and **wheel**) and publish to **test PyPI**." +msgstr "" + +#: ../../tutorials/installable-code.md:640 +msgid "" +"Finally you will learn how to [publish to **conda-forge**](publish-conda-" +"forge) from **PyPI**." +msgstr "" + +#: ../../tutorials/installable-code.md:644 +msgid "[Carpentries shell lesson](https://swcarpentry.github.io/shell-novice/)" +msgstr "" + +#: ../../tutorials/installable-code.md:646 +msgid "" +"[Python module " +"docs](https://docs.python.org/3/tutorial/modules.html#packages)" +msgstr "" + +#: ../../tutorials/installable-code.md:648 +msgid "[Numpy style docs](https://numpydoc.readthedocs.io/en/latest/format.html)" +msgstr "" + +#: ../../tutorials/installable-code.md:647 +msgid "[Google docstring style](https://google.github.io/styleguide/pyguide.html)" +msgstr "" + +#: ../../tutorials/installable-code.md:649 +msgid "[epydoc](https://epydoc.sourceforge.net/epytext.html)" +msgstr "" + +#: ../../tutorials/intro.md:27 ../../tutorials/setup-py-to-pyproject-toml.md:24 +msgid "Get to know Hatch" +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 "" + diff --git a/noxfile.py b/noxfile.py index 4a0ea835..ee44f29c 100644 --- a/noxfile.py +++ b/noxfile.py @@ -43,7 +43,7 @@ ## Localization options (translations) # List of languages for which locales will be generated in (/locales/) -LANGUAGES = ["es"] +LANGUAGES = ["es", "ja"] # List of languages that should be built when releasing the guide (docs or docs-test sessions) RELEASE_LANGUAGES = [] From a35a30c12caf959f203f68e075c44def65bf1538 Mon Sep 17 00:00:00 2001 From: Tetsuo Koyama Date: Fri, 2 Aug 2024 18:10:41 +0900 Subject: [PATCH 2/8] Revert changes of es locale --- locales/es/LC_MESSAGES/CONTRIBUTING.po | 147 +++++------ locales/es/LC_MESSAGES/tutorials.po | 321 +++++-------------------- 2 files changed, 120 insertions(+), 348 deletions(-) diff --git a/locales/es/LC_MESSAGES/CONTRIBUTING.po b/locales/es/LC_MESSAGES/CONTRIBUTING.po index 0cddd183..b2a801f4 100644 --- a/locales/es/LC_MESSAGES/CONTRIBUTING.po +++ b/locales/es/LC_MESSAGES/CONTRIBUTING.po @@ -9,7 +9,7 @@ msgid "" msgstr "" "Project-Id-Version: pyOpenSci Python Package Guide \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-08-02 18:04+0900\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" @@ -119,117 +119,96 @@ 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. To " -"\"fork\" a repository in GitHub means to create a copy of the main " -"repository, or repo, that you have complete control over and can modify " -"as you see fit." +"Python Packaging Guide repository into your personal GitHub space." msgstr "" #: ../../CONTRIBUTING.md:37 -msgid "To fork a repo," -msgstr "" - -#: ../../CONTRIBUTING.md:39 -msgid "Make sure you are logged into GitHub." -msgstr "" - -#: ../../CONTRIBUTING.md:41 msgid "" -"Go to the repo you would like to fork, in this case the [Python Packaging" -" Guide](https://www.github.com/pyopensci/python-package-guide) repo." +"*__TODO__: This section should show a beginner user how to fork a " +"repository in GitHub.*" msgstr "" -#: ../../CONTRIBUTING.md:43 -msgid "" -"In the top right-hand corner of the page there is a 'Fork' button. Click " -"that button. You will be brought to a new page where you will 'Create a " -"new fork'. Feel free to keep all the default inputs and click 'Create " -"fork'. This will create a copy of the repo at " -"`https://github.com//python-package-guide`, where `` " -"is your GitHub username." -msgstr "" - -#: ../../CONTRIBUTING.md:47 +#: ../../CONTRIBUTING.md:39 msgid "Contributing via the GitHub website" msgstr "" -#: ../../CONTRIBUTING.md:49 +#: ../../CONTRIBUTING.md:41 msgid "How to edit a MarkDown file" msgstr "" -#: ../../CONTRIBUTING.md:51 +#: ../../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:53 +#: ../../CONTRIBUTING.md:45 msgid "How to commit your changes" msgstr "" -#: ../../CONTRIBUTING.md:55 +#: ../../CONTRIBUTING.md:47 msgid "" "*__TODO__: This section should show how to commit changes via the GitHub " "interface.*" msgstr "" -#: ../../CONTRIBUTING.md:57 +#: ../../CONTRIBUTING.md:49 msgid "Contributing locally on your computer" msgstr "" -#: ../../CONTRIBUTING.md:59 +#: ../../CONTRIBUTING.md:51 msgid "Clone your forked repository" msgstr "" -#: ../../CONTRIBUTING.md:61 +#: ../../CONTRIBUTING.md:53 msgid "" "*__TODO__: This section should show how to clone a repository from GitHub" " into your computer.*" msgstr "" -#: ../../CONTRIBUTING.md:63 +#: ../../CONTRIBUTING.md:55 msgid "Create a new branch" msgstr "" -#: ../../CONTRIBUTING.md:65 +#: ../../CONTRIBUTING.md:57 msgid "*__TODO__: This section should show how to create a new branch.*" msgstr "" -#: ../../CONTRIBUTING.md:67 +#: ../../CONTRIBUTING.md:59 msgid "Create a virtual environment" msgstr "" -#: ../../CONTRIBUTING.md:69 +#: ../../CONTRIBUTING.md:61 msgid "" "*__TODO__: This section should show how to create a virtual environment " "using venv.*" msgstr "" -#: ../../CONTRIBUTING.md:71 +#: ../../CONTRIBUTING.md:63 msgid "Install the development dependencies" msgstr "" -#: ../../CONTRIBUTING.md:73 +#: ../../CONTRIBUTING.md:65 msgid "" "*__TODO__: This section should show how to install the development " "dependencies defined in pyproject.toml.*" msgstr "" -#: ../../CONTRIBUTING.md:75 +#: ../../CONTRIBUTING.md:67 msgid "Commit your changes" msgstr "" -#: ../../CONTRIBUTING.md:77 +#: ../../CONTRIBUTING.md:69 msgid "" "*__TODO__: This section should describe how to commit from the command " "line.*" msgstr "" -#: ../../CONTRIBUTING.md:79 +#: ../../CONTRIBUTING.md:71 msgid "How to build the guide locally" msgstr "" -#: ../../CONTRIBUTING.md:81 +#: ../../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 " @@ -237,85 +216,85 @@ msgid "" " browser or using the live version from docs-live*" msgstr "" -#: ../../CONTRIBUTING.md:83 +#: ../../CONTRIBUTING.md:75 msgid "Before you submit your pull request" msgstr "" -#: ../../CONTRIBUTING.md:85 +#: ../../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:87 +#: ../../CONTRIBUTING.md:79 msgid "Submitting a pull request with your contribution" msgstr "" -#: ../../CONTRIBUTING.md:89 +#: ../../CONTRIBUTING.md:81 msgid "How to make a pull request" msgstr "" -#: ../../CONTRIBUTING.md:91 +#: ../../CONTRIBUTING.md:83 msgid "" "*__TODO__: This section should describe how to make a pull request in " "GitHub.*" msgstr "" -#: ../../CONTRIBUTING.md:93 +#: ../../CONTRIBUTING.md:85 msgid "What happens when you submit a pull request (CI/CD)" msgstr "" -#: ../../CONTRIBUTING.md:95 +#: ../../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:97 +#: ../../CONTRIBUTING.md:89 msgid "What to expect from the review process" msgstr "" -#: ../../CONTRIBUTING.md:99 +#: ../../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:101 +#: ../../CONTRIBUTING.md:93 msgid "Additional help" msgstr "" -#: ../../CONTRIBUTING.md:103 +#: ../../CONTRIBUTING.md:95 msgid "How to get help" msgstr "" -#: ../../CONTRIBUTING.md:105 +#: ../../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:107 +#: ../../CONTRIBUTING.md:99 msgid "Additional resources" msgstr "" -#: ../../CONTRIBUTING.md:109 +#: ../../CONTRIBUTING.md:101 msgid "" "*__TODO__: It should also include links to beginner documentation, like " "the GitHub docs.*" msgstr "" -#: ../../CONTRIBUTING.md:111 +#: ../../CONTRIBUTING.md:103 msgid "Annex" msgstr "" -#: ../../CONTRIBUTING.md:113 +#: ../../CONTRIBUTING.md:105 msgid "Code examples" msgstr "" -#: ../../CONTRIBUTING.md:115 +#: ../../CONTRIBUTING.md:107 msgid "" "This guide uses the [literalinclude Sphinx directive](https://www.sphinx-" "doc.org/en/master/usage/restructuredtext/directives.html#directive-" @@ -323,18 +302,18 @@ msgid "" "for use in the documentation is kept in the `examples/` folder." msgstr "" -#: ../../CONTRIBUTING.md:119 +#: ../../CONTRIBUTING.md:111 msgid "Referencing code in documentation" msgstr "" -#: ../../CONTRIBUTING.md:121 +#: ../../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:124 +#: ../../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 " @@ -344,7 +323,7 @@ msgid "" "the later can protect your example from future modifications to the code." msgstr "" -#: ../../CONTRIBUTING.md:129 +#: ../../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" @@ -352,17 +331,17 @@ msgid "" "way to keep the same documentation content even through code refactors." msgstr "" -#: ../../CONTRIBUTING.md:133 +#: ../../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:136 +#: ../../CONTRIBUTING.md:128 msgid "Creating code for documentation" msgstr "" -#: ../../CONTRIBUTING.md:138 +#: ../../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) " @@ -371,7 +350,7 @@ msgid "" "code-in-documentation)." msgstr "" -#: ../../CONTRIBUTING.md:142 +#: ../../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 " @@ -380,7 +359,7 @@ msgid "" "create a new folder in the `examples` directory." msgstr "" -#: ../../CONTRIBUTING.md:146 +#: ../../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 " @@ -389,14 +368,14 @@ msgid "" "file, new methods after all existing ones in a class." msgstr "" -#: ../../CONTRIBUTING.md:150 +#: ../../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:153 +#: ../../CONTRIBUTING.md:145 msgid "" "***⚠️ WARNING***: great care should be taken when modifying existing " "example code, especially any modification beyond appending to the end of " @@ -407,43 +386,29 @@ msgid "" "and then checking those pages in a new build." msgstr "" -#: ../../CONTRIBUTING.md:161 +#: ../../CONTRIBUTING.md:153 msgid "Example:" msgstr "" -#: ../../CONTRIBUTING.md:163 +#: ../../CONTRIBUTING.md:155 msgid "Instead of writing example code in markdown like this" msgstr "" -#: ../../CONTRIBUTING.md:174 +#: ../../CONTRIBUTING.md:166 msgid "The python can be extracted into a `.py` file" msgstr "" -#: ../../CONTRIBUTING.md:188 +#: ../../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:191 +#: ../../CONTRIBUTING.md:183 msgid "Instead of writing this" msgstr "" -#: ../../CONTRIBUTING.md:203 +#: ../../CONTRIBUTING.md:195 msgid "an example could be extracted from an existing toml file" msgstr "" - -#~ msgid "" -#~ "Independently of the approach you " -#~ "choose, the first step is to fork" -#~ " the Python Packaging Guide repository " -#~ "into your personal GitHub space." -#~ msgstr "" - -#~ msgid "" -#~ "*__TODO__: This section should show a" -#~ " beginner user how to fork a " -#~ "repository in GitHub.*" -#~ msgstr "" - diff --git a/locales/es/LC_MESSAGES/tutorials.po b/locales/es/LC_MESSAGES/tutorials.po index 137d86ab..3427e46d 100644 --- a/locales/es/LC_MESSAGES/tutorials.po +++ b/locales/es/LC_MESSAGES/tutorials.po @@ -9,7 +9,7 @@ msgid "" msgstr "" "Project-Id-Version: pyOpenSci Python Package Guide \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-08-02 18:04+0900\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" @@ -913,231 +913,116 @@ msgstr "" msgid "Discourages misuse of your package and associated code" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:1 -msgid "Get to Know Hatch" +#: ../../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](https://hatch.pypa.io/latest/). While there are [many great " -"packaging tools](/package-structure-code/python-package-build-tools) out " -"there, we have selected Hatch because:" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:8 -msgid "" -"It is an end-to-end tool that supports most of the steps required to " -"create a quality Python package. Beginners will have fewer tools to learn" -" if they use Hatch." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:11 -msgid "" -"It supports different build back-ends if you ever need to compile code in" -" other languages." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:13 -msgid "" -"As a community, pyOpenSci has decided that Hatch is a user-friendly tool " -"that supports many different scientific Python use cases." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:16 -msgid "" -"In this tutorial, you will install and get to know Hatch a bit more " -"before starting to use it." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:19 -msgid "You need two things to successfully complete this tutorial:" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:21 -msgid "You need Python installed." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:22 -msgid "You need Hatch installed." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:25 -msgid "" -"If you don't already have Python installed on your computer, Hatch will " -"do it for you when you install Hatch." +"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:29 +#: ../../tutorials/get-to-know-hatch.md:6 msgid "Install Hatch" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:31 -msgid "" -"To begin, follow the operating-system-specific instructions below to " -"install Hatch." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md -msgid "MAC" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:38 -msgid "" -"Follow the instructions " -"[here](https://hatch.pypa.io/latest/install/#installers)." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:40 -msgid "" -"Download the latest GUI installer for MAC [hatch-" -"universal.pkg](https://github.com/pypa/hatch/releases/latest/download" -"/hatch-universal.pkg)." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:41 -msgid "Run the installer and follow the setup instructions." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:42 -msgid "If your terminal is open, then restart it." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md -msgid "Windows" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:48 -msgid "" -"In your browser, download the correct `.msi` file for your system: " -"[hatch-x64.msi](https://github.com/pypa/hatch/releases/latest/download/hatch-x64.msi)" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:50 -msgid "Run your downloaded installer file and follow the on-screen instructions." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md -msgid "Linux" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:56 -msgid "" -"We suggest that you install Hatch using pipx on Linux. however, if you " -"prefer another method, check out the [Hatch installation " -"documentation](https://hatch.pypa.io/latest/install/) for other methods." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:70 +#: ../../tutorials/get-to-know-hatch.md:7 msgid "" -"Hatch can also be installed directly using " -"[pip](https://hatch.pypa.io/latest/install/#pip) or " -"[conda](https://hatch.pypa.io/latest/install/#conda). We encourage you to" -" follow the instructions above because we have found that the Hatch " -"installers for Windows and Mac are the easiest and most efficient." +"To begin, install Hatch from the command line using " +"[pipx](https://pipx.pypa.io/stable/)" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:74 +#: ../../tutorials/get-to-know-hatch.md:14 msgid "" -"Our Linux users have found success installing Hatch with pipx if they " -"already use apt install." +"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:77 -msgid "" -"Both approaches (using a graphical installer on Windows/Mac and pipx) " -"ensure that you have Hatch installed globally. A global install means " -"that Hatch is available across all of your Python environments on your " -"computer." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:82 -msgid "Check that hatch installed correctly" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:84 +#: ../../tutorials/get-to-know-hatch.md:21 msgid "" -"Once you have completed the installation instructions above, you can open" -" your terminal, and make sure that Hatch installed correctly using the " -"command below:" +"You can check that hatch is working properly by issuing a simple command " +"to get the version" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:92 -msgid "" -"*Note the version number output of `hatch --version` will likely be " -"different from the output above in this tutorial.*" +#: ../../tutorials/get-to-know-hatch.md:28 +msgid "Note the version numbers will likely be different" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:95 -msgid "Configure Hatch" +#: ../../tutorials/get-to-know-hatch.md:30 +msgid "Configure hatch" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:97 +#: ../../tutorials/get-to-know-hatch.md:32 msgid "" -"Once you have installed Hatch, you can customize its configuration. This " -"includes setting the default name and setup for every package you create." -" While this step is not required, we suggest that you do it." +"Once you have installed Hatch, you will want to customize the " +"configuration." msgstr "" -#: ../../tutorials/get-to-know-hatch.md:101 +#: ../../tutorials/get-to-know-hatch.md:34 msgid "" -"Hatch stores your configuration in a [`config.toml` " +"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:103 +#: ../../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 and update it in a text editor if you are " +"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:107 -msgid "Step 1: Open and Edit Your `config.toml` File" +#: ../../tutorials/get-to-know-hatch.md:39 +msgid "Step 1: Open and edit your `config.toml` file" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:109 +#: ../../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:112 +#: ../../tutorials/get-to-know-hatch.md:43 msgid "`hatch config explore`" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:114 +#: ../../tutorials/get-to-know-hatch.md:45 msgid "" -"This will open up a directory window that allows you to double-click on " -"the file and open it in your favorite text editor." +"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:117 +#: ../../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:125 +#: ../../tutorials/get-to-know-hatch.md:54 msgid "Step 2 - update your email and name" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:127 +#: ../../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:137 +#: ../../tutorials/get-to-know-hatch.md:64 msgid "Step 3" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:139 +#: ../../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:141 +#: ../../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 " @@ -1145,11 +1030,11 @@ msgid "" " introduce it in later tutorials." msgstr "" -#: ../../tutorials/get-to-know-hatch.md:146 +#: ../../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:184 +#: ../../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 " @@ -1158,11 +1043,11 @@ msgid "" "use it for this tutorial series." msgstr "" -#: ../../tutorials/get-to-know-hatch.md:190 +#: ../../tutorials/get-to-know-hatch.md:116 msgid "You are of course welcome to select another license." msgstr "" -#: ../../tutorials/get-to-know-hatch.md:192 +#: ../../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 @@ -1171,84 +1056,84 @@ msgstr "" msgid "Todo" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:193 +#: ../../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:196 +#: ../../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:198 +#: ../../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:200 +#: ../../tutorials/get-to-know-hatch.md:126 msgid "`hatch config show`" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:202 +#: ../../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:206 +#: ../../tutorials/get-to-know-hatch.md:130 msgid "Hatch features" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:208 +#: ../../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:211 +#: ../../tutorials/get-to-know-hatch.md:135 msgid "Comparison to other tools" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:213 +#: ../../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:216 +#: ../../tutorials/get-to-know-hatch.md:140 msgid "[More on Hatch here](hatch)" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:218 +#: ../../tutorials/get-to-know-hatch.md:142 msgid "A few features that Hatch offers" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:220 +#: ../../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:222 +#: ../../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:224 +#: ../../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:226 +#: ../../tutorials/get-to-know-hatch.md:152 msgid "What's next" msgstr "" -#: ../../tutorials/get-to-know-hatch.md:228 +#: ../../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." @@ -2153,10 +2038,6 @@ msgstr "" msgid "[epydoc](https://epydoc.sourceforge.net/epytext.html)" msgstr "" -#: ../../tutorials/intro.md:27 ../../tutorials/setup-py-to-pyproject-toml.md:24 -msgid "Get to know Hatch" -msgstr "" - #: ../../tutorials/intro.md:27 msgid "Python Packaging Tutorial Setup" msgstr "" @@ -5534,77 +5415,3 @@ msgid "" "existing functionality remains intact. Run any pre-existing tests to " "verify that everything still works as expected." msgstr "" - -#~ 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 "" - -#~ msgid "" -#~ "To begin, install Hatch from the " -#~ "command line using " -#~ "[pipx](https://pipx.pypa.io/stable/)" -#~ msgstr "" - -#~ 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 "" - -#~ msgid "" -#~ "You can check that hatch is " -#~ "working properly by issuing a simple " -#~ "command to get the version" -#~ msgstr "" - -#~ msgid "Note the version numbers will likely be different" -#~ msgstr "" - -#~ msgid "Configure hatch" -#~ msgstr "" - -#~ msgid "" -#~ "Once you have installed Hatch, you " -#~ "will want to customize the " -#~ "configuration." -#~ msgstr "" - -#~ msgid "" -#~ "Hatch stores your configuration information" -#~ " in a [`config.toml` " -#~ "file](https://hatch.pypa.io/latest/config/project-templates/)." -#~ msgstr "" - -#~ 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 "" - -#~ msgid "Step 1: Open and edit your `config.toml` file" -#~ msgstr "" - -#~ 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 "" - From dbc8206da81f758e5b089d4781554c6efe881822 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 2 Aug 2024 09:13:22 +0000 Subject: [PATCH 3/8] =?UTF-8?q?'[pre-commit.ci=20=F0=9F=A4=96]=20Apply=20c?= =?UTF-8?q?ode=20format=20tools=20to=20PR'?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- locales/ja/LC_MESSAGES/CONTRIBUTING.po | 1 - locales/ja/LC_MESSAGES/TRANSLATING.po | 1 - locales/ja/LC_MESSAGES/documentation.po | 1 - locales/ja/LC_MESSAGES/index.po | 1 - locales/ja/LC_MESSAGES/package-structure-code.po | 1 - locales/ja/LC_MESSAGES/tests.po | 1 - locales/ja/LC_MESSAGES/tutorials.po | 1 - 7 files changed, 7 deletions(-) diff --git a/locales/ja/LC_MESSAGES/CONTRIBUTING.po b/locales/ja/LC_MESSAGES/CONTRIBUTING.po index 3c3eee6f..16c831c9 100644 --- a/locales/ja/LC_MESSAGES/CONTRIBUTING.po +++ b/locales/ja/LC_MESSAGES/CONTRIBUTING.po @@ -433,4 +433,3 @@ msgstr "" #: ../../CONTRIBUTING.md:203 msgid "an example could be extracted from an existing toml file" msgstr "" - diff --git a/locales/ja/LC_MESSAGES/TRANSLATING.po b/locales/ja/LC_MESSAGES/TRANSLATING.po index 707de067..13765fc7 100644 --- a/locales/ja/LC_MESSAGES/TRANSLATING.po +++ b/locales/ja/LC_MESSAGES/TRANSLATING.po @@ -715,4 +715,3 @@ msgid "" " as a way for contributors to ask for help with translations or the " "translation workflow?" msgstr "" - diff --git a/locales/ja/LC_MESSAGES/documentation.po b/locales/ja/LC_MESSAGES/documentation.po index 8a849f4a..ea6bdd72 100644 --- a/locales/ja/LC_MESSAGES/documentation.po +++ b/locales/ja/LC_MESSAGES/documentation.po @@ -2543,4 +2543,3 @@ msgstr "" #: ../../documentation/write-user-documentation/intro.md:15 msgid "sphinx gallery for tutorials." msgstr "" - diff --git a/locales/ja/LC_MESSAGES/index.po b/locales/ja/LC_MESSAGES/index.po index 6d662248..379d9450 100644 --- a/locales/ja/LC_MESSAGES/index.po +++ b/locales/ja/LC_MESSAGES/index.po @@ -481,4 +481,3 @@ msgid "" " in the Python packaging ecosystem. We will be adding new content over " "the next year." msgstr "" - diff --git a/locales/ja/LC_MESSAGES/package-structure-code.po b/locales/ja/LC_MESSAGES/package-structure-code.po index e409630c..f02e7e1e 100644 --- a/locales/ja/LC_MESSAGES/package-structure-code.po +++ b/locales/ja/LC_MESSAGES/package-structure-code.po @@ -5299,4 +5299,3 @@ 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/ja/LC_MESSAGES/tests.po b/locales/ja/LC_MESSAGES/tests.po index 540e03ab..1b5994c6 100644 --- a/locales/ja/LC_MESSAGES/tests.po +++ b/locales/ja/LC_MESSAGES/tests.po @@ -1000,4 +1000,3 @@ msgid "" "the user can easily understand why if failed (provides a useful error " "message)." msgstr "" - diff --git a/locales/ja/LC_MESSAGES/tutorials.po b/locales/ja/LC_MESSAGES/tutorials.po index 6f88c534..7eb0df48 100644 --- a/locales/ja/LC_MESSAGES/tutorials.po +++ b/locales/ja/LC_MESSAGES/tutorials.po @@ -5534,4 +5534,3 @@ msgid "" "existing functionality remains intact. Run any pre-existing tests to " "verify that everything still works as expected." msgstr "" - From 257d20520726b03e3dbfbb7a28b0f70680b88848 Mon Sep 17 00:00:00 2001 From: Tetsuo Koyama Date: Fri, 2 Aug 2024 18:23:48 +0900 Subject: [PATCH 4/8] Revert "Create empty translation files for Japanese" This reverts commit bcdb31abc17957425c486688a198c50df1d3fa04. --- locales/ja/LC_MESSAGES/CONTRIBUTING.po | 436 -- locales/ja/LC_MESSAGES/TRANSLATING.po | 718 --- locales/ja/LC_MESSAGES/documentation.po | 2546 -------- locales/ja/LC_MESSAGES/index.po | 484 -- .../ja/LC_MESSAGES/package-structure-code.po | 5302 ---------------- locales/ja/LC_MESSAGES/tests.po | 1003 --- locales/ja/LC_MESSAGES/tutorials.po | 5537 ----------------- noxfile.py | 2 +- 8 files changed, 1 insertion(+), 16027 deletions(-) delete mode 100644 locales/ja/LC_MESSAGES/CONTRIBUTING.po delete mode 100644 locales/ja/LC_MESSAGES/TRANSLATING.po delete mode 100644 locales/ja/LC_MESSAGES/documentation.po delete mode 100644 locales/ja/LC_MESSAGES/index.po delete mode 100644 locales/ja/LC_MESSAGES/package-structure-code.po delete mode 100644 locales/ja/LC_MESSAGES/tests.po delete mode 100644 locales/ja/LC_MESSAGES/tutorials.po diff --git a/locales/ja/LC_MESSAGES/CONTRIBUTING.po b/locales/ja/LC_MESSAGES/CONTRIBUTING.po deleted file mode 100644 index 3c3eee6f..00000000 --- a/locales/ja/LC_MESSAGES/CONTRIBUTING.po +++ /dev/null @@ -1,436 +0,0 @@ -# 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-08-02 18:04+0900\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language: ja\n" -"Language-Team: ja \n" -"Plural-Forms: nplurals=1; plural=0;\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. To " -"\"fork\" a repository in GitHub means to create a copy of the main " -"repository, or repo, that you have complete control over and can modify " -"as you see fit." -msgstr "" - -#: ../../CONTRIBUTING.md:37 -msgid "To fork a repo," -msgstr "" - -#: ../../CONTRIBUTING.md:39 -msgid "Make sure you are logged into GitHub." -msgstr "" - -#: ../../CONTRIBUTING.md:41 -msgid "" -"Go to the repo you would like to fork, in this case the [Python Packaging" -" Guide](https://www.github.com/pyopensci/python-package-guide) repo." -msgstr "" - -#: ../../CONTRIBUTING.md:43 -msgid "" -"In the top right-hand corner of the page there is a 'Fork' button. Click " -"that button. You will be brought to a new page where you will 'Create a " -"new fork'. Feel free to keep all the default inputs and click 'Create " -"fork'. This will create a copy of the repo at " -"`https://github.com//python-package-guide`, where `` " -"is your GitHub username." -msgstr "" - -#: ../../CONTRIBUTING.md:47 -msgid "Contributing via the GitHub website" -msgstr "" - -#: ../../CONTRIBUTING.md:49 -msgid "How to edit a MarkDown file" -msgstr "" - -#: ../../CONTRIBUTING.md:51 -msgid "" -"*__TODO__: This section should show how to use the GitHub interface to " -"edit and previewing a Markdown file.*" -msgstr "" - -#: ../../CONTRIBUTING.md:53 -msgid "How to commit your changes" -msgstr "" - -#: ../../CONTRIBUTING.md:55 -msgid "" -"*__TODO__: This section should show how to commit changes via the GitHub " -"interface.*" -msgstr "" - -#: ../../CONTRIBUTING.md:57 -msgid "Contributing locally on your computer" -msgstr "" - -#: ../../CONTRIBUTING.md:59 -msgid "Clone your forked repository" -msgstr "" - -#: ../../CONTRIBUTING.md:61 -msgid "" -"*__TODO__: This section should show how to clone a repository from GitHub" -" into your computer.*" -msgstr "" - -#: ../../CONTRIBUTING.md:63 -msgid "Create a new branch" -msgstr "" - -#: ../../CONTRIBUTING.md:65 -msgid "*__TODO__: This section should show how to create a new branch.*" -msgstr "" - -#: ../../CONTRIBUTING.md:67 -msgid "Create a virtual environment" -msgstr "" - -#: ../../CONTRIBUTING.md:69 -msgid "" -"*__TODO__: This section should show how to create a virtual environment " -"using venv.*" -msgstr "" - -#: ../../CONTRIBUTING.md:71 -msgid "Install the development dependencies" -msgstr "" - -#: ../../CONTRIBUTING.md:73 -msgid "" -"*__TODO__: This section should show how to install the development " -"dependencies defined in pyproject.toml.*" -msgstr "" - -#: ../../CONTRIBUTING.md:75 -msgid "Commit your changes" -msgstr "" - -#: ../../CONTRIBUTING.md:77 -msgid "" -"*__TODO__: This section should describe how to commit from the command " -"line.*" -msgstr "" - -#: ../../CONTRIBUTING.md:79 -msgid "How to build the guide locally" -msgstr "" - -#: ../../CONTRIBUTING.md:81 -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:83 -msgid "Before you submit your pull request" -msgstr "" - -#: ../../CONTRIBUTING.md:85 -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:87 -msgid "Submitting a pull request with your contribution" -msgstr "" - -#: ../../CONTRIBUTING.md:89 -msgid "How to make a pull request" -msgstr "" - -#: ../../CONTRIBUTING.md:91 -msgid "" -"*__TODO__: This section should describe how to make a pull request in " -"GitHub.*" -msgstr "" - -#: ../../CONTRIBUTING.md:93 -msgid "What happens when you submit a pull request (CI/CD)" -msgstr "" - -#: ../../CONTRIBUTING.md:95 -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:97 -msgid "What to expect from the review process" -msgstr "" - -#: ../../CONTRIBUTING.md:99 -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:101 -msgid "Additional help" -msgstr "" - -#: ../../CONTRIBUTING.md:103 -msgid "How to get help" -msgstr "" - -#: ../../CONTRIBUTING.md:105 -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:107 -msgid "Additional resources" -msgstr "" - -#: ../../CONTRIBUTING.md:109 -msgid "" -"*__TODO__: It should also include links to beginner documentation, like " -"the GitHub docs.*" -msgstr "" - -#: ../../CONTRIBUTING.md:111 -msgid "Annex" -msgstr "" - -#: ../../CONTRIBUTING.md:113 -msgid "Code examples" -msgstr "" - -#: ../../CONTRIBUTING.md:115 -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:119 -msgid "Referencing code in documentation" -msgstr "" - -#: ../../CONTRIBUTING.md:121 -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:124 -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:129 -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:133 -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:136 -msgid "Creating code for documentation" -msgstr "" - -#: ../../CONTRIBUTING.md:138 -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:142 -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:146 -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:150 -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:153 -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:161 -msgid "Example:" -msgstr "" - -#: ../../CONTRIBUTING.md:163 -msgid "Instead of writing example code in markdown like this" -msgstr "" - -#: ../../CONTRIBUTING.md:174 -msgid "The python can be extracted into a `.py` file" -msgstr "" - -#: ../../CONTRIBUTING.md:188 -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:191 -msgid "Instead of writing this" -msgstr "" - -#: ../../CONTRIBUTING.md:203 -msgid "an example could be extracted from an existing toml file" -msgstr "" - diff --git a/locales/ja/LC_MESSAGES/TRANSLATING.po b/locales/ja/LC_MESSAGES/TRANSLATING.po deleted file mode 100644 index 707de067..00000000 --- a/locales/ja/LC_MESSAGES/TRANSLATING.po +++ /dev/null @@ -1,718 +0,0 @@ -# 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-08-02 18:04+0900\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language: ja\n" -"Language-Team: ja \n" -"Plural-Forms: nplurals=1; plural=0;\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/ja/LC_MESSAGES/documentation.po b/locales/ja/LC_MESSAGES/documentation.po deleted file mode 100644 index 8a849f4a..00000000 --- a/locales/ja/LC_MESSAGES/documentation.po +++ /dev/null @@ -1,2546 +0,0 @@ -# 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-08-02 18:04+0900\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language: ja\n" -"Language-Team: ja \n" -"Plural-Forms: nplurals=1; plural=0;\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://pyopensci.org/badges/peer-" -"reviewed.svg)](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/ja/LC_MESSAGES/index.po b/locales/ja/LC_MESSAGES/index.po deleted file mode 100644 index 6d662248..00000000 --- a/locales/ja/LC_MESSAGES/index.po +++ /dev/null @@ -1,484 +0,0 @@ -# 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-08-02 18:04+0900\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language: ja\n" -"Language-Team: ja \n" -"Plural-Forms: nplurals=1; plural=0;\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" - -#: ../../index.md:283 -msgid "Tutorials" -msgstr "" - -#: ../../index.md:289 -msgid "Packaging" -msgstr "" - -#: ../../index.md:139 ../../index.md:297 -msgid "Documentation" -msgstr "" - -#: ../../index.md:187 ../../index.md:305 -msgid "Tests" -msgstr "" - -#: ../../index.md:305 -msgid "Testing" -msgstr "" - -#: ../../index.md:1 -msgid "pyOpenSci Python Package Guide" -msgstr "" - -#: ../../index.md:3 -msgid "" -"We support the Python tools that scientists need to create open science " -"workflows." -msgstr "" - -#: ../../index.md:20 -msgid "" -"![GitHub release (latest by " -"date)](https://img.shields.io/github/v/release/pyopensci/python-package-" -"guide?color=purple&display_name=tag&style=plastic) " -"[![](https://img.shields.io/github/stars/pyopensci/python-package-" -"guide?style=social)](https://github.com/pyopensci/contributing-guide) " -"[![DOI](https://zenodo.org/badge/556814582.svg)](https://zenodo.org/badge/latestdoi/556814582)" -msgstr "" - -#: ../../index.md:20 -msgid "GitHub release (latest by date)" -msgstr "" - -#: ../../index.md:20 -msgid "DOI" -msgstr "" - -#: ../../index.md:27 -msgid "About this guide" -msgstr "" - -#: ../../index.md:29 -msgid "" -"Image with the pyOpenSci flower logo in the upper right hand corner. The " -"image shows the packaging lifecycle. The graphic shows a high level " -"overview of the elements of a Python package. the inside circle has 5 " -"items - user documentation, code/api, test suite, contributor " -"documentation, project metadata / license / readme. In the middle of the " -"circle is says maintainers and has a small icon with people. on the " -"outside circle there is an arrow and it says infrastructure." -msgstr "" - -#: ../../index.md:35 -msgid "This guide will help you:" -msgstr "" - -#: ../../index.md:37 -msgid "Learn how to create a Python package from start to finish" -msgstr "" - -#: ../../index.md:38 -msgid "Understand the broader Python packaging tool ecosystem" -msgstr "" - -#: ../../index.md:39 -msgid "Navigate and make decisions around tool options" -msgstr "" - -#: ../../index.md:40 -msgid "Understand all of the pieces of creating and maintaining a Python package" -msgstr "" - -#: ../../index.md:42 -msgid "" -"You will also find best practice recommendations and curated lists of " -"community resources surrounding packaging and package documentation." -msgstr "" - -#: ../../index.md:46 -msgid "Todo" -msgstr "" - -#: ../../index.md:47 -msgid "TODO: change the navigation of docs to have a" -msgstr "" - -#: ../../index.md:49 -msgid "user documentation contributor / maintainer documentation" -msgstr "" - -#: ../../index.md:51 -msgid "development guide" -msgstr "" - -#: ../../index.md:52 -msgid "contributing guide" -msgstr "" - -#: ../../index.md:54 -msgid "Community docs" -msgstr "" - -#: ../../index.md:55 -msgid "readme, coc, license" -msgstr "" - -#: ../../index.md:57 -msgid "Publish your docs" -msgstr "" - -#: ../../index.md:59 -msgid "_new_ Tutorial Series: Create a Python Package" -msgstr "" - -#: ../../index.md:61 -msgid "" -"The first round of our community-developed, how to create a Python " -"package tutorial series for scientists is complete! Join our community " -"review process or watch development of future tutorials in our [Github " -"repo here](https://github.com/pyOpenSci/python-package-guide)." -msgstr "" - -#: ../../index.md:71 -msgid "✿ Create a Package Tutorials ✿" -msgstr "" - -#: ../../index.md:75 -msgid "[What is a Python package?](/tutorials/intro)" -msgstr "" - -#: ../../index.md:76 -msgid "[Make your code installable](/tutorials/installable-code)" -msgstr "" - -#: ../../index.md:77 -msgid "[Publish your package to (test) PyPI](/tutorials/publish-pypi)" -msgstr "" - -#: ../../index.md:78 -msgid "[Publish your package to conda-forge](/tutorials/publish-conda-forge)" -msgstr "" - -#: ../../index.md:83 -msgid "✿ Package Metadata Tutorials ✿" -msgstr "" - -#: ../../index.md:87 -msgid "[How to add a README file](/tutorials/add-readme)" -msgstr "" - -#: ../../index.md:88 -msgid "" -"[How to add metadata to a pyproject.toml file for publication to " -"PyPI.](/tutorials/pyproject-toml.md)" -msgstr "" - -#: ../../index.md:93 -msgid "✿ Packaging Tool Tutorials ✿" -msgstr "" - -#: ../../index.md:97 -msgid "[Introduction to Hatch](/tutorials/get-to-know-hatch)" -msgstr "" - -#: ../../index.md:102 -msgid "Python Packaging for Scientists" -msgstr "" - -#: ../../index.md:104 -msgid "" -"Learn about Python packaging best practices. You will also get to know " -"the the vibrant ecosystem of packaging tools that are available to help " -"you with your Python packaging needs." -msgstr "" - -#: ../../index.md:113 -msgid "✨ Create your package ✨" -msgstr "" - -#: ../../index.md:117 -msgid "[Package file structure](/package-structure-code/python-package-structure)" -msgstr "" - -#: ../../index.md:118 -msgid "" -"[Package metadata / pyproject.toml](package-structure-code/pyproject-" -"toml-python-package-metadata.md)" -msgstr "" - -#: ../../index.md:119 -msgid "" -"[Build your package (sdist / wheel)](package-structure-code/python-" -"package-distribution-files-sdist-wheel.md)" -msgstr "" - -#: ../../index.md:120 -msgid "[Declare dependencies](package-structure-code/declare-dependencies.md)" -msgstr "" - -#: ../../index.md:121 -msgid "" -"[Navigate the packaging tool ecosystem](package-structure-code/python-" -"package-build-tools.md)" -msgstr "" - -#: ../../index.md:122 -msgid "" -"[Non pure Python builds](package-structure-code/complex-python-package-" -"builds.md)" -msgstr "" - -#: ../../index.md:127 -msgid "✨ Publish your package ✨" -msgstr "" - -#: ../../index.md:131 -msgid "" -"Gain a better understanding of the Python packaging ecosystem Learn about" -" best practices for:" -msgstr "" - -#: ../../index.md:134 -msgid "" -"[Package versioning & release](/package-structure-code/python-package-" -"versions.md)" -msgstr "" - -#: ../../index.md:135 -msgid "" -"[Publish to PyPI & Conda-forge](/package-structure-code/publish-python-" -"package-pypi-conda.md)" -msgstr "" - -#: ../../index.md:148 -msgid "✨ Write The Docs ✨" -msgstr "" - -#: ../../index.md:151 -msgid "" -"[Create documentation for your users](/documentation/write-user-" -"documentation/intro)" -msgstr "" - -#: ../../index.md:152 -msgid "" -"[Core files to include in your package repository](/documentation" -"/repository-files/intro)" -msgstr "" - -#: ../../index.md:153 -msgid "" -"[Write tutorials to show how your package is used](/documentation/write-" -"user-documentation/create-package-tutorials)" -msgstr "" - -#: ../../index.md:158 -msgid "✨ Developer Docs ✨" -msgstr "" - -#: ../../index.md:161 -msgid "" -"[Create documentation for collaborating developers](/documentation" -"/repository-files/contributing-file)" -msgstr "" - -#: ../../index.md:162 -msgid "" -"[Write a development guide](/documentation/repository-files/development-" -"guide)" -msgstr "" - -#: ../../index.md:167 -msgid "✨ Document For A Community ✨" -msgstr "" - -#: ../../index.md:170 -msgid "" -"[Writing a README file](/documentation/repository-files/readme-file-best-" -"practices)" -msgstr "" - -#: ../../index.md:171 -msgid "" -"[Set norms with a Code of Conduct](/documentation/repository-files/code-" -"of-conduct-file)" -msgstr "" - -#: ../../index.md:172 -msgid "[License your package](/documentation/repository-files/license-files)" -msgstr "" - -#: ../../index.md:177 -msgid "✨ Publish Your Docs ✨" -msgstr "" - -#: ../../index.md:180 -msgid "[How to publish your docs](/documentation/hosting-tools/intro)" -msgstr "" - -#: ../../index.md:181 -msgid "[Using Sphinx](/documentation/hosting-tools/intro)" -msgstr "" - -#: ../../index.md:182 -msgid "" -"[Markdown, MyST, and ReST](/documentation/hosting-tools/myst-markdown-" -"rst-doc-syntax)" -msgstr "" - -#: ../../index.md:183 -msgid "" -"[Host your docs on Read The Docs or Github Pages](/documentation/hosting-" -"tools/publish-documentation-online)" -msgstr "" - -#: ../../index.md:189 -msgid "" -"*We are actively working on this section. [Follow development " -"here.](https://github.com/pyOpenSci/python-package-guide)*" -msgstr "" - -#: ../../index.md:197 -msgid "✨ Tests for your Python package ✨" -msgstr "" - -#: ../../index.md:200 -msgid "[Intro to testing](tests/index.md)" -msgstr "" - -#: ../../index.md:201 -msgid "[Write tests](tests/write-tests)" -msgstr "" - -#: ../../index.md:202 -msgid "[Types of tests](tests/test-types)" -msgstr "" - -#: ../../index.md:207 -msgid "✨ Run your tests ✨" -msgstr "" - -#: ../../index.md:210 -msgid "[Run tests locally](tests/run-tests)" -msgstr "" - -#: ../../index.md:211 -msgid "[Run tests in CI](tests/tests-ci)" -msgstr "" - -#: ../../index.md:215 -msgid "Contributing" -msgstr "" - -#: ../../index.md:225 -msgid "✨ Code style & Format ✨" -msgstr "" - -#: ../../index.md:230 -msgid "[Code style](package-structure-code/code-style-linting-format.md)" -msgstr "" - -#: ../../index.md:235 -msgid "✨ Want to contribute? ✨" -msgstr "" - -#: ../../index.md:240 -msgid "" -"We welcome contributions to this guide. Learn more about how you can " -"contribute." -msgstr "" - -#: ../../index.md:246 -msgid "" -"xkcd comic showing a stick figure on the ground and one in the air. The " -"one on the ground is saying. `You're flying! how?` The person in the air" -" replies `Python!` Below is a 3 rectangle comic with the following text " -"in each box. box 1 - I learned it last night. Everything is so simple. " -"Hello world is just print hello world. box 2 - the person on the ground " -"says - come join us programming is fun again. it's a whole new world. But" -" how are you flying? box 3 - the person flying says - i just typed import" -" antigravity. I also sampled everything in the medicine cabinet. But i " -"think this is the python. the person on the ground is saying - that's it?" -msgstr "" - -#: ../../index.md:252 -msgid "A community-created guidebook" -msgstr "" - -#: ../../index.md:254 -msgid "" -"Every page in this guidebook goes through an extensive community review " -"process. To ensure our guidebook is both beginner-friendly and accurate, " -"we encourage reviews from a diverse set of pythonistas and scientists " -"with a wide range of skills and expertise." -msgstr "" - -#: ../../index.md:257 -msgid "View guidebook contributors" -msgstr "" - -#: ../../index.md:265 -msgid "Who this guidebook is for" -msgstr "" - -#: ../../index.md:267 -msgid "" -"This guidebook is for anyone interested in learning more about Python " -"packaging. It is beginner-friendly and will provide:" -msgstr "" - -#: ../../index.md:269 -msgid "Beginning-to-end guidance on creating a Python package." -msgstr "" - -#: ../../index.md:270 -msgid "" -"Resources to help you navigate the Python packaging ecosystem of tools " -"and approaches to packaging." -msgstr "" - -#: ../../index.md:271 -msgid "" -"A curated list of resources to help you get your package into documented," -" usable and maintainable shape." -msgstr "" - -#: ../../index.md:273 -msgid "Where this guide is headed" -msgstr "" - -#: ../../index.md:275 -msgid "" -"If you have ideas of things you'd like to see here clarified in this " -"guide, [we invite you to open an issue on " -"GitHub.](https://github.com/pyOpenSci/python-package-guide/issues)." -msgstr "" - -#: ../../index.md:278 -msgid "" -"If you have questions about our peer review process or packaging in " -"general, you are welcome to use our [pyOpenSci Discourse " -"forum](https://pyopensci.discourse.group/)." -msgstr "" - -#: ../../index.md:280 -msgid "" -"This is a living guide that is updated as tools and best practices evolve" -" in the Python packaging ecosystem. We will be adding new content over " -"the next year." -msgstr "" - diff --git a/locales/ja/LC_MESSAGES/package-structure-code.po b/locales/ja/LC_MESSAGES/package-structure-code.po deleted file mode 100644 index e409630c..00000000 --- a/locales/ja/LC_MESSAGES/package-structure-code.po +++ /dev/null @@ -1,5302 +0,0 @@ -# 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-08-02 18:04+0900\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language: ja\n" -"Language-Team: ja \n" -"Plural-Forms: nplurals=1; plural=0;\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:182 -msgid "Python file `temporal.py` imports after `isort` has been run" -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:189 -msgid "Ruff" -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:191 -msgid "" -"[Ruff](https://docs.astral.sh/ruff/) is a new addition to the code " -"quality ecosystem, gaining some traction since its release. `ruff` is " -"both a linter and a code formatter for Python, aiming to replace several " -"tools behind a single interface. As such, `ruff` can be used at a " -"replacement of all other tools mentioned here, or in complement to some " -"of them." -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:197 -msgid "" -"`ruff` has some interesting features that distinguish it from other " -"linters:" -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:199 -msgid "Linter configuration in `pyproject.toml`" -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:200 -msgid "Several hundred rules included, many of which are automatically fixable" -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:201 -msgid "" -"Rules explanation, see [F403](https://docs.astral.sh/ruff/rules" -"/undefined-local-with-import-star/) for an example" -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:202 -msgid "" -"Fast execution time, makes a quick feedback loop possible even on large " -"projects." -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:204 -msgid "" -"Here is a simple configuration to get started with `ruff`. It would go " -"into your `pyproject.toml`:" -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:212 -msgid "" -"Depending on your project, you might want to add the following to sort " -"imports correctly:" -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:219 -msgid "How to use code formatter in your local workflow" -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:221 -msgid "Linters, code formatters and your favorite coding tools" -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:223 -msgid "" -"Linters can be run as a command-line tool as shown above. They also can " -"be run within your favorite coding tool (e.g. VScode, pycharm, etc). For " -"example, you might prefer to have tools like Black and isort run when you" -" save a file. In some editors you can also setup shortcuts that run your " -"favorite code format tools on demand." -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:229 -msgid "Use pre-commit hooks to run code formatters and linters on commits" -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:231 -msgid "You can also setup a `pre-commit hook` in your Python package repository." -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:233 -msgid "" -"A pre-commit hook is a tool that allows an action (or actions) to be " -"triggered when you apply a commit to your git repository." -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:236 -msgid "Pre-commit hook example workflow" -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:238 -msgid "The precommit workflow looks like this: You type and run:" -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:241 -msgid "`git commit -m \"message here\"` at the command line" -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:243 -msgid "" -"Once you hit return, pre-commit will run any tools that you have " -"configured in a **.pre-commit-config.yaml** file." -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:245 -msgid "" -"If the tools configured in the pre-commit hook run successfully without " -"making changes or finding errors in your code, the commit will be applied" -" to the repository." -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:249 -msgid "" -"If the tools configured in the hook find errors in your files, the commit" -" will NOT be applied to the repository. Remember from the discussion " -"above that a code formatter like Black will run and reformat your code. A" -" linter like _flake8_ will provide you with some output that details " -"where there are syntax issues in your code. You will then need to fix " -"those issues, manually." -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:256 -msgid "" -"Once all of the fixes are applied you can re-add (stage) the files to be " -"commit. And re-run your commit." -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:260 -msgid "Diagram showing the steps of a pre-commit workflow from left to right." -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:262 -msgid "" -"The pre-commit workflow begins with you adding files that have changes to" -" be staged in git. Next, you'd run git commit. when you run git commit, " -"the pre-commit hooks will then run. In this example, Black, the code " -"formatter and flake8, a linter both run. If all of the files pass Black " -"and flake8 checks, then your commit will be recorded. If they don't, the " -"commit is canceled. You will have to fix any flake8 issues, and then re-" -"add / stage the files to be committed. [_Image " -"Source_](https://ljvmiranda921.github.io/notebook/2018/06/21/precommits-" -"using-black-and-flake8/*)" -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:275 -msgid "" -"If have a Python code-base and multiple maintainers actively working on " -"the code, and you intend to run a tool like Black, be sure to coordinate " -"across your team. An initial commit that applies Black to your entire " -"package will likely change a significant amount of your code. This could " -"lead to merge conflicts on open and new PR's before the new changes are " -"merged." -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:282 -msgid "General pre commit checks" -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:284 -msgid "" -"In addition to calling tools, Pre-commit also has a suite of [built in " -"format hooks](https://github.com/pre-commit/pre-commit-hooks#hooks-" -"available) that you can call. Some, such as trailing-whitespace can be " -"also useful to add to your pre-commit workflow to ensure clean, " -"streamlined code files." -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:289 -msgid "" -"An example pre-commit-config.yaml file is below with examples of how this" -" is all setup." -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:292 -msgid "Pre-commit.ci" -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:294 -msgid "" -"[Pre-commit.ci](https://pre-commit.ci) is a bot that may become your new " -"best friend. This bot, when setup on a repo can be configured to do the " -"following:" -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:297 -msgid "It will check every pull request using all of the pre-commit hook setting" -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:298 -msgid "" -"If you wish, it will also submit a pull request to your repo with pre-" -"commit fixes, saving you, and new contributors the time of reformatting a" -" pr that has format issues." -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:301 -msgid "You can also call the bot on any pull request to run / and fix the code." -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:303 -msgid "" -"The pre-commit.ci bot uses the same pre-commit-config.yaml file that you " -"use to setup pre-commit locally." -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:306 -msgid "Setting up a bot like this can be valuable because:" -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:308 -msgid "" -"It can make is easier for maintainers as they no longer have to worry at " -"allows about fixing code format. The bot will do the work for them." -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:310 -msgid "" -"It can make it easier for new comers as they never have to setup pre-" -"commit locally or worry about linting their code. They can even make " -"small fixes to the code directly on GitHub without worry." -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:312 -msgid "Setting up a git pre-commit hook" -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:314 -msgid "To setup pre-commit locally, you need to do 3 things:" -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:316 -msgid "" -"Install pre-commit (and include it as a development requirement in your " -"repository)" -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:326 -msgid "" -"Create a .pre-commit-config.yaml file in the root of your package " -"directory." -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:328 -msgid "" -"Below is an example **.pre-commit-cofig.yaml** file that can be used to " -"setup the pre-commit hook and the pre-commit.ci bot if you chose to " -"implement that too." -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:336 -msgid "" -"This file specifies a hook that will be triggered automatically before " -"each `git commit`, in this case, it specifies a `flake8` using version " -"`6.0.0`." -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:339 -msgid "" -"Install your pre-commit hook(s) using `pre-commit install`. This will " -"install all of the hooks specified in the pre-commit yaml file into your " -"environment." -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:341 -msgid "" -"Once you have done the above, you are ready to start working on your " -"code. Pre-commit will run every time you run `git commit`." -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:344 -msgid "Summary" -msgstr "" - -#: ../../package-structure-code/code-style-linting-format.md:346 -msgid "" -"pyOpenSci suggests setting up a linter and a code styler for your " -"package, regardless of whether you use pre-commit hooks, CI or other " -"infrastructure to manage code format. Setting up these tools will give " -"you automatic feedback about your code's structure as you (or a " -"contributor) write it. And using a tool like black that format code for " -"you, reduce effort that you need to make surrounding decisions around " -"code format and style." -msgstr "" - -#: ../../package-structure-code/complex-python-package-builds.md:1 -msgid "Complex Python package builds" -msgstr "" - -#: ../../package-structure-code/complex-python-package-builds.md:3 -msgid "" -"This guide is focused on packages that are either pure-python or that " -"have a few simple extensions in another language such as C or C++." -msgstr "" - -#: ../../package-structure-code/complex-python-package-builds.md:6 -msgid "" -"In the future, we want to provide resources for packaging workflows that " -"require more complex builds. If you have questions about these types of " -"package, please [add a question to our " -"discourse](https://pyopensci.discourse.group/) or open an [issue about " -"this guide specifically in the GitHub repo for this " -"guide](https://github.com/pyOpenSci/python-package-guide/issues). There " -"are many nuances to building and distributing Python packages that have " -"compiled extensions requiring non-Python dependencies at build time. For " -"an overview and thorough discussion of these nuances, please see [this " -"site.](https://pypackaging-native.github.io/)" -msgstr "" - -#: ../../package-structure-code/complex-python-package-builds.md:8 -msgid "Pure Python Packages vs. packages with extensions in other languages" -msgstr "" - -#: ../../package-structure-code/complex-python-package-builds.md:10 -msgid "" -"You can classify Python package complexity into three general categories." -" These categories can in turn help you select the correct package " -"frontend and backend tools." -msgstr "" - -#: ../../package-structure-code/complex-python-package-builds.md:14 -msgid "" -"**Pure-python packages:** these are packages that only rely on Python to " -"function. Building a pure Python package is simpler. As such, you can " -"chose a tool below that has the features that you want and be done with " -"your decision!" -msgstr "" - -#: ../../package-structure-code/complex-python-package-builds.md:16 -msgid "" -"**Python packages with non-Python extensions:** These packages have " -"additional components called extensions written in other languages (such " -"as C or C++). If you have a package with non-Python extensions, then you " -"need to select a build backend tool that allows additional build steps " -"needed to compile your extension code. Further, if you wish to use a " -"frontend tool to support your workflow, you will need to select a tool " -"that supports additional build setups. We suggest that you chose build " -"tool that supports custom build steps like Hatch." -msgstr "" - -#: ../../package-structure-code/complex-python-package-builds.md:18 -msgid "" -"**Python packages that have extensions written in different languages " -"(e.g. Fortran and C++) or that have non Python dependencies that are " -"difficult to install (e.g. GDAL)** These packages often have complex " -"build steps (more complex than a package with just a few C extensions for" -" instance). As such, these packages require tools such as [scikit-" -"build](https://scikit-build.readthedocs.io/en/latest/) or [meson-" -"python](https://mesonbuild.com/Python-module.html) to build. NOTE: you " -"can use meson-python with PDM." -msgstr "" - -#: ../../package-structure-code/complex-python-package-builds.md:21 -msgid "Mixing frontend and backend projects" -msgstr "" - -#: ../../package-structure-code/complex-python-package-builds.md:23 -msgid "" -"It is sometimes necessary or desirable to use a build frontend with an " -"alternative build-backend. This is because some frontends do not have a " -"default backend (`build`), and this choice is placed on the maintainer. " -"Other backends (`hatch`) have a preferred backend (`hatchling`) but allow" -" the maintainer to migrate to another, while some backends (`poetry`) " -"only work with a single backend (`poetry-core`). Refer to (#python-" -"package-build-tools) for more information about frontend and backend " -"compatibility." -msgstr "" - -#: ../../package-structure-code/complex-python-package-builds.md:29 -msgid "" -"In this packaging guide we recommend using `hatch` along with its " -"preferred backend `hatchling`. While this will be suitable for most " -"packages, an alternate backend may be used with Hatch if needed when " -"creating an extension module. A Python extension module is one that is " -"made up, either in part or entirely, of compiled code. In this case the " -"backend chosen (such as `meson-python`) must know how to compile the " -"extension language and bind it to Python. `hatchling` does not know how " -"to do this all on its own and must either make use of " -"[plugins](https://hatch.pypa.io/1.9/plugins/about/) or be replaced by a " -"backend that is already capable of building extension modules." -msgstr "" - -#: ../../package-structure-code/complex-python-package-builds.md:37 -msgid "" -"In order to use a different backend you will need to edit your project's " -"`pyproject.toml`. If you have a `pyproject.toml` generated by the `hatch`" -" command, or from following the packaging tutorial, you may have to make " -"a change like this" -msgstr "" - -#: ../../package-structure-code/declare-dependencies.md:8 -#: ../../package-structure-code/declare-dependencies.md:375 -#: ../../package-structure-code/pyproject-toml-python-package-metadata.md: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/ja/LC_MESSAGES/tests.po b/locales/ja/LC_MESSAGES/tests.po deleted file mode 100644 index 540e03ab..00000000 --- a/locales/ja/LC_MESSAGES/tests.po +++ /dev/null @@ -1,1003 +0,0 @@ -# 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-08-02 18:04+0900\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language: ja\n" -"Language-Team: ja \n" -"Plural-Forms: nplurals=1; plural=0;\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" - -#: ../../tests/index.md:72 -msgid "Intro" -msgstr "" - -#: ../../tests/index.md:72 -msgid "Write tests" -msgstr "" - -#: ../../tests/index.md:72 -msgid "Test types" -msgstr "" - -#: ../../tests/index.md:72 -msgid "Run tests locally" -msgstr "" - -#: ../../tests/index.md:72 -msgid "Run tests online (using CI)" -msgstr "" - -#: ../../tests/index.md:72 -msgid "Create & Run Tests" -msgstr "" - -#: ../../tests/index.md:1 -msgid "Tests and data for your Python package" -msgstr "" - -#: ../../tests/index.md:3 -msgid "" -"Tests are an important part of your Python package because they provide a" -" set of checks that ensure that your package is functioning how you " -"expect it to." -msgstr "" - -#: ../../tests/index.md:7 -msgid "" -"In this section you will learn more about the importance of writing tests" -" for your Python package and how you can setup infrastructure to run your" -" tests both locally and on GitHub." -msgstr "" - -#: ../../tests/index.md:19 -msgid "✨ Why write tests ✨" -msgstr "" - -#: ../../tests/index.md:24 -msgid "" -"Learn more about the art of writing tests for your Python package. Learn " -"about why you should write tests and how they can help you and potential " -"contributors to your project." -msgstr "" - -#: ../../tests/index.md:31 -msgid "✨ Types of tests ✨" -msgstr "" - -#: ../../tests/index.md:36 -msgid "" -"There are three general types of tests that you can write for your Python" -" package: unit tests, integration tests and end-to-end (or functional) " -"tests. Learn about all three." -msgstr "" - -#: ../../tests/index.md:42 -msgid "✨ Run tests locally ✨" -msgstr "" - -#: ../../tests/index.md:47 -msgid "" -"If you expect your users to use your package across different versions of" -" Python, then using an automation tool such as nox to run your tests is " -"useful. Learn about the various tools that you can use to run your tests " -"across python versions here." -msgstr "" - -#: ../../tests/index.md:53 -msgid "✨ Run tests online (using CI) ✨" -msgstr "" - -#: ../../tests/index.md:58 -msgid "" -"Continuous integration platforms such as GitHub actions can be useful for" -" running your tests across both different Python versions and different " -"operating systems. Learn about setting up tests to run in Continuous " -"Integration here." -msgstr "" - -#: ../../tests/index.md:69 -msgid "Graphic showing the elements of the packaging process." -msgstr "" - -#: ../../tests/run-tests.md:6 -msgid "Run Python package tests" -msgstr "" - -#: ../../tests/run-tests.md:8 -msgid "" -"Running your tests is important to ensure that your package is working as" -" expected. It's good practice to consider that tests will run on your " -"computer and your users' computers that may be running a different Python" -" version and operating systems. Think about the following when running " -"your tests:" -msgstr "" - -#: ../../tests/run-tests.md:11 -msgid "" -"Run your test suite in a matrix of environments that represent the Python" -" versions and operating systems your users are likely to have." -msgstr "" - -#: ../../tests/run-tests.md:12 -msgid "" -"Running your tests in an isolated environment provides confidence in the " -"tests and their reproducibility. This ensures that tests do not pass " -"randomly due to your computer's specific setup. For instance, you might " -"have unexpectedly installed dependencies on your local system that are " -"not declared in your package's dependency list. This oversight could lead" -" to issues when others try to install or run your package on their " -"computers." -msgstr "" - -#: ../../tests/run-tests.md:14 -msgid "" -"On this page, you will learn about the tools that you can use to both run" -" tests in isolated environments and across Python versions." -msgstr "" - -#: ../../tests/run-tests.md:19 -msgid "Tools to run your tests" -msgstr "" - -#: ../../tests/run-tests.md:21 -msgid "" -"There are three categories of tools that will make is easier to setup and" -" run your tests in various environments:" -msgstr "" - -#: ../../tests/run-tests.md:24 -msgid "" -"A **test framework**, is a package that provides a particular syntax and " -"set of tools for _both writing and running your tests_. Some test " -"frameworks also have plugins that add additional features such as " -"evaluating how much of your code the tests cover. Below you will learn " -"about the **pytest** framework which is one of the most commonly used " -"Python testing frameworks in the scientific ecosystem. Testing frameworks" -" are essential but they only serve to run your tests. These frameworks " -"don't provide a way to easily run tests across Python versions without " -"the aid of additional automation tools." -msgstr "" - -#: ../../tests/run-tests.md:25 -msgid "" -"**Automation tools** allow you to automate running workflows such as " -"tests in specific ways using user-defined commands. For instance it's " -"useful to be able to run tests across different Python versions with a " -"single command. Tools such as " -"[**nox**](https://nox.thea.codes/en/stable/index.html) and " -"[**tox**](https://tox.wiki/en/latest/index.html) also allow you to run " -"tests across Python versions. However, it will be difficult to test your " -"build on different operating systems using only nox and tox - this is " -"where continuous integration (CI) comes into play." -msgstr "" - -#: ../../tests/run-tests.md:26 -msgid "" -"**Continuous Integration (CI):** is the last tool that you'll need to run" -" your tests. CI will not only allow you to replicate any automated builds" -" you create using nox or tox to run your package in different Python " -"environments. It will also allow you to run your tests on different " -"operating systems (Windows, Mac and Linux). [We discuss using CI to run " -"tests here](tests-ci)." -msgstr "" - -#: ../../tests/run-tests.md:28 -msgid "Table: Testing & Automation Tool" -msgstr "" - -#: ../../tests/run-tests.md:35 -msgid "Features" -msgstr "" - -#: ../../tests/run-tests.md:36 -msgid "Testing Framework (pytest)" -msgstr "" - -#: ../../tests/run-tests.md:37 -msgid "Test Runner (Tox)" -msgstr "" - -#: ../../tests/run-tests.md:38 -msgid "Automation Tools (Nox)" -msgstr "" - -#: ../../tests/run-tests.md:39 -msgid "Continuous Integration (GitHub Actions)" -msgstr "" - -#: ../../tests/run-tests.md:40 -msgid "Run Tests Locally" -msgstr "" - -#: ../../tests/run-tests.md:41 ../../tests/run-tests.md:42 -#: ../../tests/run-tests.md:43 ../../tests/run-tests.md:49 -#: ../../tests/run-tests.md:52 ../../tests/run-tests.md:53 -#: ../../tests/run-tests.md:54 ../../tests/run-tests.md:57 -#: ../../tests/run-tests.md:58 ../../tests/run-tests.md:59 -#: ../../tests/run-tests.md:64 ../../tests/run-tests.md:68 -#: ../../tests/run-tests.md:69 -msgid "" -msgstr "" - -#: ../../tests/run-tests.md:44 ../../tests/run-tests.md:46 -#: ../../tests/run-tests.md:47 ../../tests/run-tests.md:48 -#: ../../tests/run-tests.md:51 ../../tests/run-tests.md:56 -#: ../../tests/run-tests.md:61 ../../tests/run-tests.md:62 -#: ../../tests/run-tests.md:63 ../../tests/run-tests.md:66 -#: ../../tests/run-tests.md:67 -msgid "" -msgstr "" - -#: ../../tests/run-tests.md:45 -msgid "Run Tests Online" -msgstr "" - -#: ../../tests/run-tests.md:50 -msgid "Run Tests Across Python Versions" -msgstr "" - -#: ../../tests/run-tests.md:55 -msgid "Run Tests In Isolated Environments" -msgstr "" - -#: ../../tests/run-tests.md:60 -msgid "Run Tests Across Operating Systems (Windows, MacOS, Linux)" -msgstr "" - -#: ../../tests/run-tests.md:65 -msgid "Use for other automation tasks (e.g. building docs)" -msgstr "" - -#: ../../tests/run-tests.md:73 -msgid "What testing framework / package should I use to run tests?" -msgstr "" - -#: ../../tests/run-tests.md:75 -msgid "" -"We recommend using `Pytest` to build and run your package tests. Pytest " -"is the most common testing tool used in the Python ecosystem." -msgstr "" - -#: ../../tests/run-tests.md:77 -msgid "" -"[The Pytest package](https://docs.pytest.org/en/latest/) also has a " -"number of extensions that can be used to add functionality such as:" -msgstr "" - -#: ../../tests/run-tests.md:80 -msgid "" -"[pytest-cov](https://pytest-cov.readthedocs.io/en/latest/) allows you to " -"analyze the code coverage of your package during your tests, and " -"generates a report that you can [upload to codecov](https://codecov.io/)." -msgstr "" - -#: ../../tests/run-tests.md:82 ../../tests/run-tests.md:174 -#: ../../tests/test-types.md:14 ../../tests/tests-ci.md:7 -msgid "Todo" -msgstr "" - -#: ../../tests/run-tests.md:83 -msgid "Learn more about code coverage here. (add link)" -msgstr "" - -#: ../../tests/run-tests.md:87 -msgid "" -"Your editor or IDE may add additional convenience for running tests, " -"setting breakpoints, and toggling the `–no-cov` flag. Check your editor's" -" documentation for more information." -msgstr "" - -#: ../../tests/run-tests.md:90 -msgid "Run tests using pytest" -msgstr "" - -#: ../../tests/run-tests.md:92 -msgid "If you are using **pytest**, you can run your tests locally by calling:" -msgstr "" - -#: ../../tests/run-tests.md:95 -msgid "`pytest`" -msgstr "" - -#: ../../tests/run-tests.md:97 -msgid "" -"Or if you want to run a specific test file - let's call this file " -"\"`test_module.py`\" - you can run:" -msgstr "" - -#: ../../tests/run-tests.md:99 -msgid "`pytest test_module.py`" -msgstr "" - -#: ../../tests/run-tests.md:101 -msgid "" -"Learn more from the [get started docs](https://docs.pytest.org/en/7.1.x" -"/getting-started.html)." -msgstr "" - -#: ../../tests/run-tests.md:103 -msgid "" -"Running pytest on your computer is going to run your tests in whatever " -"Python environment you currently have activated. This means that tests " -"will be run on a single version of Python and only on the operating " -"system that you are running locally." -msgstr "" - -#: ../../tests/run-tests.md:108 -msgid "" -"An automation tool can simplify the process of running tests in various " -"Python environments." -msgstr "" - -#: ../../tests/run-tests.md:111 -msgid "Tests across operating systems" -msgstr "" - -#: ../../tests/run-tests.md:112 -msgid "" -"If you want to run your tests across different operating systems you can " -"[continuous integration. Learn more here](tests-ci)." -msgstr "" - -#: ../../tests/run-tests.md:115 -msgid "Tools to automate running your tests" -msgstr "" - -#: ../../tests/run-tests.md:117 -msgid "" -"To run tests on various Python versions or in various specific " -"environments with a single command, you can use an automation tool such " -"as `nox` or `tox`. Both `nox` and `tox` can create an isolated virtual " -"environments. This allows you to easily run your tests in multiple " -"environments and across Python versions." -msgstr "" - -#: ../../tests/run-tests.md:120 -msgid "" -"We will focus on [Nox](https://nox.thea.codes/) in this guide. `nox` is a" -" Python-based automation tool that builds upon the features of both " -"`make` and `tox`. `nox` is designed to simplify and streamline testing " -"and development workflows. Everything that you do with `nox` can be " -"implemented using a Python-based interface." -msgstr "" - -#: ../../tests/run-tests.md:122 -msgid "Other automation tools you'll see in the wild" -msgstr "" - -#: ../../tests/run-tests.md:125 -msgid "" -"**[Tox](https://tox.wiki/en/latest/index.html#useful-links)** is an " -"automation tool that supports common steps such as building " -"documentation, running tests across various versions of Python, and more." -" You can find [a nice overview of tox in the plasmaPy " -"documentation](https://docs.plasmapy.org/en/stable/contributing/testing_guide.html" -"#using-tox)." -msgstr "" - -#: ../../tests/run-tests.md:127 -msgid "" -"**[Hatch](https://github.com/ofek/hatch)** is a modern end-to-end " -"packaging tool that works with the popular build backend called " -"hatchling. `hatch` offers a `tox`-like setup where you can run tests " -"locally using different Python versions. If you are using `hatch` to " -"support your packaging workflow, you may want to also use its testing " -"capabilities rather than using `nox`." -msgstr "" - -#: ../../tests/run-tests.md:129 -msgid "" -"[**make:**](https://www.gnu.org/software/make/manual/make.html) Some " -"developers use Make, which is a build automation tool, for running tests " -"due to its versatility; it's not tied to a specific language and can be " -"used to run various build processes. However, Make's unique syntax and " -"approach can make it more challenging to learn, particularly if you're " -"not already familiar with it. Make also won't manage environments for you" -" like **nox** will do." -msgstr "" - -#: ../../tests/run-tests.md:136 -msgid "Run tests across Python versions with nox" -msgstr "" - -#: ../../tests/run-tests.md:138 -msgid "**Nox** is a great automation tool to learn because it:" -msgstr "" - -#: ../../tests/run-tests.md:140 -msgid "Is Python-based making it accessible if you already know Python and" -msgstr "" - -#: ../../tests/run-tests.md:141 -msgid "Will create isolated environments to run workflows." -msgstr "" - -#: ../../tests/run-tests.md:143 -msgid "" -"`nox` simplifies creating and managing testing environments. With `nox`, " -"you can set up virtual environments, and run tests across Python versions" -" using the environment manager of your choice with a single command." -msgstr "" - -#: ../../tests/run-tests.md:148 -msgid "Nox Installations" -msgstr "" - -#: ../../tests/run-tests.md:150 -msgid "" -"When you install and use nox to run tests across different Python " -"versions, nox will create and manage individual `venv` environments for " -"each Python version that you specify in the nox function." -msgstr "" - -#: ../../tests/run-tests.md:152 -msgid "Nox will manage each environment on its own." -msgstr "" - -#: ../../tests/run-tests.md:154 -msgid "" -"Nox can also be used for other development tasks such as building " -"documentation, creating your package distribution, and testing " -"installations across both PyPI related environments (e.g. venv, " -"virtualenv) and `conda` (e.g. `conda-forge`)." -msgstr "" - -#: ../../tests/run-tests.md:158 -msgid "" -"To get started with nox, you create a `noxfile.py` file at the root of " -"your project directory. You then define commands using Python functions. " -"Some examples of that are below." -msgstr "" - -#: ../../tests/run-tests.md:162 -msgid "Test Environments" -msgstr "" - -#: ../../tests/run-tests.md:164 -msgid "" -"By default, `nox` uses the Python built in `venv` environment manager. A " -"virtual environment (`venv`) is a self-contained Python environment that " -"allows you to isolate and manage dependencies for different Python " -"projects. It helps ensure that project-specific libraries and packages do" -" not interfere with each other, promoting a clean and organized " -"development environment." -msgstr "" - -#: ../../tests/run-tests.md:166 -msgid "" -"An example of using nox to run tests in `venv` environments for Python " -"versions 3.9, 3.10, 3.11 and 3.12 is below." -msgstr "" - -#: ../../tests/run-tests.md:169 -msgid "" -"Note that for the code below to work, you need to have all 4 versions of " -"Python installed on your computer for `nox` to find." -msgstr "" - -#: ../../tests/run-tests.md:172 -msgid "Nox with venv environments" -msgstr "" - -#: ../../tests/run-tests.md:175 -msgid "" -"TODO: add some tests above and show what the output would look like in " -"the examples below..." -msgstr "" - -#: ../../tests/run-tests.md:178 -msgid "" -"Below is an example of setting up nox to run tests using `venv` which is " -"the built in environment manager that comes with base Python." -msgstr "" - -#: ../../tests/run-tests.md:180 -msgid "" -"Note that the example below assumes that you have [setup your " -"`pyproject.toml` to declare test dependencies in a way that pip can " -"understand](../package-structure-code/declare-dependencies.md). An " -"example of that setup is below." -msgstr "" - -#: ../../tests/run-tests.md:201 -msgid "" -"If you have the above setup, then you can use " -"`session.install(\".[tests]\")` to install your test dependencies. Notice" -" that below one single nox session allows you to run your tests on 4 " -"different Python environments (Python 3.9, 3.10, 3.11, and 3.12)." -msgstr "" - -#: ../../tests/run-tests.md:222 -msgid "" -"Above you create a nox session in the form of a function with a " -"`@nox.session` decorator. Notice that within the decorator you declare " -"the versions of python that you wish to run." -msgstr "" - -#: ../../tests/run-tests.md:226 -msgid "" -"To run the above you'd execute the following command, specifying which " -"session with `--session` (sometimes shortened to `-s`). Your function " -"above is called test, therefore the session name is test." -msgstr "" - -#: ../../tests/run-tests.md:234 -msgid "Nox with conda / mamba" -msgstr "" - -#: ../../tests/run-tests.md:236 -msgid "" -"Below is an example for setting up nox to use mamba (or conda) for your " -"environment manager. Note that unlike venv, conda can automatically " -"install the various versions of Python that you need. You won't need to " -"install all four Python versions if you use conda/mamba, like you do with" -" `venv`." -msgstr "" - -#: ../../tests/run-tests.md:242 -msgid "" -"For `conda` to work with `nox`, you will need to ensure that either " -"`conda` or `mamba` is installed on your computer." -msgstr "" - -#: ../../tests/run-tests.md:264 -msgid "To run the above session you'd use:" -msgstr "" - -#: ../../tests/test-types.md:1 -msgid "Test Types for Python packages" -msgstr "" - -#: ../../tests/test-types.md:3 -msgid "Three types of tests: Unit, Integration & Functional Tests" -msgstr "" - -#: ../../tests/test-types.md:5 -msgid "" -"There are different types of tests that you want to consider when " -"creating your test suite:" -msgstr "" - -#: ../../tests/test-types.md:8 -msgid "Unit tests" -msgstr "" - -#: ../../tests/test-types.md:9 -msgid "Integration" -msgstr "" - -#: ../../tests/test-types.md:10 -msgid "End-to-end (also known as Functional) tests" -msgstr "" - -#: ../../tests/test-types.md:12 -msgid "" -"Each type of test has a different purpose. Here, you will learn about all" -" three types of tests." -msgstr "" - -#: ../../tests/test-types.md:15 -msgid "" -"I think this page would be stronger if we did have some examples from our" -" package here: https://github.com/pyOpenSci/pyosPackage" -msgstr "" - -#: ../../tests/test-types.md:20 -msgid "Unit Tests" -msgstr "" - -#: ../../tests/test-types.md:22 -msgid "" -"A unit test involves testing individual components or units of code in " -"isolation to ensure that they work correctly. The goal of unit testing is" -" to verify that each part of the software, typically at the function or " -"method level, performs its intended task correctly." -msgstr "" - -#: ../../tests/test-types.md:24 -msgid "" -"Unit tests can be compared to examining each piece of your puzzle to " -"ensure parts of it are not broken. If all of the pieces of your puzzle " -"don’t fit together, you will never complete it. Similarly, when working " -"with code, tests ensure that each function, attribute, class, method " -"works properly when isolated." -msgstr "" - -#: ../../tests/test-types.md:26 -msgid "" -"**Unit test example:** Pretend that you have a function that converts a " -"temperature value from Celsius to Fahrenheit. A test for that function " -"might ensure that when provided with a value in Celsius, the function " -"returns the correct value in degrees Fahrenheit. That function is a unit " -"test. It checks a single unit (function) in your code." -msgstr "" - -#: ../../tests/test-types.md:44 -msgid "" -"Example unit test for the above function. You'd run this test using the " -"`pytest` command in your **tests/** directory." -msgstr "" - -#: ../../tests/test-types.md:65 ../../tests/test-types.md:115 -msgid "" -"image of puzzle pieces that all fit together nicely. The puzzle pieces " -"are colorful - purple, green and teal." -msgstr "" - -#: ../../tests/test-types.md:69 -msgid "" -"Your unit tests should ensure each part of your code works as expected on" -" its own." -msgstr "" - -#: ../../tests/test-types.md:72 -msgid "Integration tests" -msgstr "" - -#: ../../tests/test-types.md:74 -msgid "" -"Integration tests involve testing how parts of your package work together" -" or integrate. Integration tests can be compared to connecting a bunch of" -" puzzle pieces together to form a whole picture. Integration tests focus " -"on how different pieces of your code fit and work together." -msgstr "" - -#: ../../tests/test-types.md:76 -msgid "" -"For example, if you had a series of steps that collected temperature data" -" in a spreadsheet, converted it from degrees celsius to Fahrenheit and " -"then provided an average temperature for a particular time period. An " -"integration test would ensure that all parts of that workflow behaved as " -"expected." -msgstr "" - -#: ../../tests/test-types.md:107 -msgid "" -"image of two puzzle pieces with some missing parts. The puzzle pieces are" -" purple teal yellow and blue. The shapes of each piece don’t fit " -"together." -msgstr "" - -#: ../../tests/test-types.md:112 -msgid "" -"If puzzle pieces have missing ends, they can’t work together with other " -"elements in the puzzle. The same is true with individual functions, " -"methods and classes in your software. The code needs to work both " -"individually and together to perform certain sets of tasks." -msgstr "" - -#: ../../tests/test-types.md:120 -msgid "" -"Your integration tests should ensure that parts of your code that are " -"expected to work together, do so as expected." -msgstr "" - -#: ../../tests/test-types.md:124 -msgid "End-to-end (functional) tests" -msgstr "" - -#: ../../tests/test-types.md:126 -msgid "" -"End-to-end tests (also referred to as functional tests) in Python are " -"like comprehensive checklists for your software. They simulate real user " -"end-to-end workflows to make sure the code base supports real life " -"applications and use-cases from start to finish. These tests help catch " -"issues that might not show up in smaller tests and ensure your entire " -"application or program behaves correctly. Think of them as a way to give " -"your software a final check before it's put into action, making sure it's" -" ready to deliver a smooth experience to its users." -msgstr "" - -#: ../../tests/test-types.md:128 -msgid "Image of a completed puzzle showing a daisy" -msgstr "" - -#: ../../tests/test-types.md:133 -msgid "" -"End-to-end or functional tests represent an entire workflow that you " -"expect your package to support." -msgstr "" - -#: ../../tests/test-types.md:137 -msgid "" -"End-to-end test also test how a program runs from start to finish. A " -"tutorial that you add to your documentation that runs in CI in an " -"isolated environment is another example of an end-to-end test." -msgstr "" - -#: ../../tests/test-types.md:140 -msgid "" -"For scientific packages, creating short tutorials that highlight core " -"workflows that your package supports, that are run when your " -"documentation is built could also serve as end-to-end tests." -msgstr "" - -#: ../../tests/test-types.md:143 -msgid "Comparing unit, integration and end-to-end tests" -msgstr "" - -#: ../../tests/test-types.md:145 -msgid "" -"Unit tests, integration tests, and end-to-end tests have complementary " -"advantages and disadvantages. The fine-grained nature of unit tests make " -"them well-suited for isolating where errors are occurring. However, unit " -"tests are not useful for verifying that different sections of code work " -"together." -msgstr "" - -#: ../../tests/test-types.md:147 -msgid "" -"Integration and end-to-end tests verify that the different portions of " -"the program work together, but are less well-suited for isolating where " -"errors are occurring. For example, when you refactor your code, it is " -"possible that that your end-to-end tests will break. But if the refactor " -"didn't introduce new behavior to your existing code, then you can rely on" -" your unit tests to continue to pass, testing the original functionality " -"of your code." -msgstr "" - -#: ../../tests/test-types.md:152 -msgid "" -"It is important to note that you don't need to spend energy worrying " -"about the specifics surrounding the different types of tests. When you " -"begin to work on your test suite, consider what your package does and how" -" you may need to test parts of your package. Bring familiar with the " -"different types of tests can provides a framework to help you think about" -" writing tests and how different types of tests can complement each " -"other." -msgstr "" - -#: ../../tests/tests-ci.md:1 -msgid "Run tests with Continuous Integration" -msgstr "" - -#: ../../tests/tests-ci.md:3 -msgid "" -"Running your [test suite locally](run-tests) is useful as you develop " -"code and also test new features or changes to the code base. However, you" -" also will want to setup Continuous Integration (CI) to run your tests " -"online. CI allows you to run all of your tests in the cloud. While you " -"may only be able to run tests locally on a specific operating system, " -"using CI you can specify tests to run both on various versions of Python " -"and across different operating systems." -msgstr "" - -#: ../../tests/tests-ci.md:5 -msgid "" -"CI can also be triggered for pull requests and pushes to your repository." -" This means that every pull request that you, your maintainer team or a " -"contributor submit, can be tested. In the end CI testing ensures your " -"code continues to run as expected even as changes are made to the code " -"base." -msgstr "" - -#: ../../tests/tests-ci.md:9 -msgid "" -"Learn more about Continuous Integration and how it can be used, here. " -"(add link)" -msgstr "" - -#: ../../tests/tests-ci.md:13 -msgid "CI & pull requests" -msgstr "" - -#: ../../tests/tests-ci.md:15 -msgid "" -"CI is invaluable if you have outside people contributing to your " -"software. You can setup CI to run on all pull requests submitted to your " -"repository. CI can make your repository more friendly to new potential " -"contributors. It allows users to contribute code, documentation fixes and" -" more without having to create development environments, run tests and " -"build documentation locally." -msgstr "" - -#: ../../tests/tests-ci.md:22 -msgid "Example GitHub action that runs tests" -msgstr "" - -#: ../../tests/tests-ci.md:24 -msgid "" -"Below is an example GitHub action that runs tests using nox across both " -"Windows, Mac and Linux and on Python versions 3.9-3.11." -msgstr "" - -#: ../../tests/tests-ci.md:28 -msgid "" -"To work properly, this file should be located in a root directory of your" -" GitHub repository:" -msgstr "" - -#: ../../tests/write-tests.md:1 -msgid "Write tests for your Python package" -msgstr "" - -#: ../../tests/write-tests.md:3 -msgid "" -"Writing code that tests your package code, also known as test suites, is " -"important for you as a maintainer, your users, and package contributors. " -"Test suites consist of sets of functions, methods, and classes that are " -"written with the intention of making sure a specific part of your code " -"works as you expected it to." -msgstr "" - -#: ../../tests/write-tests.md:7 -msgid "Why write tests for your package?" -msgstr "" - -#: ../../tests/write-tests.md:9 -msgid "" -"Tests act as a safety net for code changes. They help you spot and " -"rectify bugs before they affect users. Tests also instill confidence that" -" code alterations from contributors won't breaking existing " -"functionality." -msgstr "" - -#: ../../tests/write-tests.md:13 -msgid "Writing tests for your Python package is important because:" -msgstr "" - -#: ../../tests/write-tests.md:15 -msgid "" -"**Catch Mistakes:** Tests are a safety net. When you make changes or add " -"new features to your package, tests can quickly tell you if you " -"accidentally broke something that was working fine before." -msgstr "" - -#: ../../tests/write-tests.md:16 -msgid "" -"**Save Time:** Imagine you have a magic button that can automatically " -"check if your package is still working properly. Tests are like that " -"magic button! They can run all those checks for you saving you time." -msgstr "" - -#: ../../tests/write-tests.md:17 -msgid "" -"**Easier Collaboration:** If you're working with others, or have outside " -"contributors, tests help everyone stay on the same page. Your tests " -"explain how your package is supposed to work, making it easier for others" -" to understand and contribute to your project." -msgstr "" - -#: ../../tests/write-tests.md:18 -msgid "" -"**Fearless Refactoring:** Refactoring means making improvements to your " -"code structure without changing its behavior. Tests empower you to make " -"these changes as if you break something, test failures will let you know." -msgstr "" - -#: ../../tests/write-tests.md:19 -msgid "" -"**Documentation:** Tests serve as technical examples of how to use your " -"package. This can be helpful for a new technical contributor that wants " -"to contribute code to your package. They can look at your tests to " -"understand how parts of your code functionality fits together." -msgstr "" - -#: ../../tests/write-tests.md:20 -msgid "" -"**Long-Term ease of maintenance:** As your package evolves, tests ensure " -"that your code continues to behave as expected, even as you make changes " -"over time. Thus you are helping your future self when writing tests." -msgstr "" - -#: ../../tests/write-tests.md:21 -msgid "" -"**Easier pull request reviews:** By running your tests in a CI framework " -"such as GitHub actions, each time you or a contributor makes a change to " -"your code-base, you can catch issues and things that may have changed in " -"your code base. This ensures that your software behaves the way you " -"expect it to." -msgstr "" - -#: ../../tests/write-tests.md:23 -msgid "Tests for user edge cases" -msgstr "" - -#: ../../tests/write-tests.md:25 -msgid "" -"Edge cases refer to unexpected or \"outlier\" ways that some users may " -"use your package. Tests enable you to address various edge cases that " -"could impair your package's functionality. For example, what occurs if a " -"function expects a pandas `dataframe` but a user supplies a numpy " -"`array`? Does your code gracefully handle this situation, providing clear" -" feedback, or does it leave users frustrated by an unexplained failure?" -msgstr "" - -#: ../../tests/write-tests.md:33 -msgid "" -"For a good introduction to testing, see [this Software Carpentry " -"lesson](https://swcarpentry.github.io/python-novice-" -"inflammation/10-defensive.html)" -msgstr "" - -#: ../../tests/write-tests.md:41 -msgid "" -"Imagine you're working on a puzzle where each puzzle piece represents a " -"function, method, class or attribute in your Python package that you want" -" other people to be able to use. Would you want to give someone a puzzle " -"that has missing pieces or pieces that don't fit together? Providing " -"people with the right puzzle pieces that work together can be compared to" -" writing tests for your Python package." -msgstr "" - -#: ../../tests/write-tests.md:44 -msgid "Test examples" -msgstr "" - -#: ../../tests/write-tests.md:47 -msgid "" -"Let’s say you have a Python function that adds two numbers a and b " -"together." -msgstr "" - -#: ../../tests/write-tests.md:54 -msgid "" -"A test to ensure that function runs as you might expect when provided " -"with different numbers might look like this:" -msgstr "" - -#: ../../tests/write-tests.md:72 -msgid "🧩🐍" -msgstr "" - -#: ../../tests/write-tests.md:74 -msgid "How do I know what type of tests to write?" -msgstr "" - -#: ../../tests/write-tests.md:77 -msgid "" -"This section has been adapted from [a presentation by Nick " -"Murphy](https://zenodo.org/record/8185113)." -msgstr "" - -#: ../../tests/write-tests.md:80 -msgid "" -"At this point, you may be wondering - what should you be testing in your " -"package? Below are a few examples:" -msgstr "" - -#: ../../tests/write-tests.md:82 -msgid "" -"**Test some typical cases:** Test that the package functions as you " -"expect it to when users use it. For instance, if your package is supposed" -" to add two numbers, test that the outcome value of adding those two " -"numbers is correct." -msgstr "" - -#: ../../tests/write-tests.md:84 -msgid "" -"**Test special cases:** Sometimes there are special or outlier cases. For" -" instance, if a function performs a specific calculation that may become " -"problematic closer to the value = 0, test it with the input of both 0 and" -msgstr "" - -#: ../../tests/write-tests.md:86 -msgid "" -"**Test at and near the expected boundaries:** If a function requires a " -"value that is greater than or equal to 1, make sure that the function " -"still works with both the values 1 and less than one and 1.001 as well " -"(something close to the constraint value).." -msgstr "" - -#: ../../tests/write-tests.md:88 -msgid "" -"**Test that code fails correctly:** If a function requires a value " -"greater than or equal to 1, then test at 0.999. Make sure that the " -"function fails gracefully when given unexpected values and help and that " -"the user can easily understand why if failed (provides a useful error " -"message)." -msgstr "" - diff --git a/locales/ja/LC_MESSAGES/tutorials.po b/locales/ja/LC_MESSAGES/tutorials.po deleted file mode 100644 index 6f88c534..00000000 --- a/locales/ja/LC_MESSAGES/tutorials.po +++ /dev/null @@ -1,5537 +0,0 @@ -# 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-08-02 18:04+0900\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language: ja\n" -"Language-Team: ja \n" -"Plural-Forms: nplurals=1; plural=0;\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 -msgid "Get to Know Hatch" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:3 -msgid "" -"Our Python packaging tutorials use the tool " -"[Hatch](https://hatch.pypa.io/latest/). While there are [many great " -"packaging tools](/package-structure-code/python-package-build-tools) out " -"there, we have selected Hatch because:" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:8 -msgid "" -"It is an end-to-end tool that supports most of the steps required to " -"create a quality Python package. Beginners will have fewer tools to learn" -" if they use Hatch." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:11 -msgid "" -"It supports different build back-ends if you ever need to compile code in" -" other languages." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:13 -msgid "" -"As a community, pyOpenSci has decided that Hatch is a user-friendly tool " -"that supports many different scientific Python use cases." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:16 -msgid "" -"In this tutorial, you will install and get to know Hatch a bit more " -"before starting to use it." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:19 -msgid "You need two things to successfully complete this tutorial:" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:21 -msgid "You need Python installed." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:22 -msgid "You need Hatch installed." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:25 -msgid "" -"If you don't already have Python installed on your computer, Hatch will " -"do it for you when you install Hatch." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:29 -msgid "Install Hatch" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:31 -msgid "" -"To begin, follow the operating-system-specific instructions below to " -"install Hatch." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md -msgid "MAC" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:38 -msgid "" -"Follow the instructions " -"[here](https://hatch.pypa.io/latest/install/#installers)." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:40 -msgid "" -"Download the latest GUI installer for MAC [hatch-" -"universal.pkg](https://github.com/pypa/hatch/releases/latest/download" -"/hatch-universal.pkg)." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:41 -msgid "Run the installer and follow the setup instructions." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:42 -msgid "If your terminal is open, then restart it." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md -msgid "Windows" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:48 -msgid "" -"In your browser, download the correct `.msi` file for your system: " -"[hatch-x64.msi](https://github.com/pypa/hatch/releases/latest/download/hatch-x64.msi)" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:50 -msgid "Run your downloaded installer file and follow the on-screen instructions." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md -msgid "Linux" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:56 -msgid "" -"We suggest that you install Hatch using pipx on Linux. however, if you " -"prefer another method, check out the [Hatch installation " -"documentation](https://hatch.pypa.io/latest/install/) for other methods." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:70 -msgid "" -"Hatch can also be installed directly using " -"[pip](https://hatch.pypa.io/latest/install/#pip) or " -"[conda](https://hatch.pypa.io/latest/install/#conda). We encourage you to" -" follow the instructions above because we have found that the Hatch " -"installers for Windows and Mac are the easiest and most efficient." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:74 -msgid "" -"Our Linux users have found success installing Hatch with pipx if they " -"already use apt install." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:77 -msgid "" -"Both approaches (using a graphical installer on Windows/Mac and pipx) " -"ensure that you have Hatch installed globally. A global install means " -"that Hatch is available across all of your Python environments on your " -"computer." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:82 -msgid "Check that hatch installed correctly" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:84 -msgid "" -"Once you have completed the installation instructions above, you can open" -" your terminal, and make sure that Hatch installed correctly using the " -"command below:" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:92 -msgid "" -"*Note the version number output of `hatch --version` will likely be " -"different from the output above in this tutorial.*" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:95 -msgid "Configure Hatch" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:97 -msgid "" -"Once you have installed Hatch, you can customize its configuration. This " -"includes setting the default name and setup for every package you create." -" While this step is not required, we suggest that you do it." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:101 -msgid "" -"Hatch stores your configuration in a [`config.toml` " -"file](https://hatch.pypa.io/latest/config/project-templates/)." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:103 -msgid "" -"While you can update the `config.toml` file through the command line, it " -"might be easier to look at and update it in a text editor if you are " -"using it for the first time." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:107 -msgid "Step 1: Open and Edit Your `config.toml` File" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:109 -msgid "" -"To open the config file in your file browser, run the following command " -"in your shell:" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:112 -msgid "`hatch config explore`" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:114 -msgid "" -"This will open up a directory window that allows you to double-click on " -"the file and open it in your favorite text editor." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:117 -msgid "" -"You can also retrieve the location of the Hatch config file by running " -"the following command in your shell:" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:125 -msgid "Step 2 - update your email and name" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:127 -msgid "" -"Once the file is open, update the [template] table of the `config.toml` " -"file with your name and email. This information will be used in any " -"`pyproject.toml` metadata files that you create using Hatch." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:137 -msgid "Step 3" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:139 -msgid "Next, set tests to false in the `[template.plugins.default]` table." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:141 -msgid "" -"While tests are important, setting the tests configuration in Hatch to " -"`true` will create a more complex `pyproject.toml` file. You won't need " -"to use this feature in this beginner friendly tutorial series but we will" -" introduce it in later tutorials." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:146 -msgid "Your `config.toml` file should look something like the one below." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:184 -msgid "" -"Also notice that the default license option is MIT. While we will discuss" -" license in more detail in a later lesson, the MIT license is the " -"recommended permissive license from " -"[choosealicense.com](https://www.choosealicense.com) and as such we will " -"use it for this tutorial series." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:190 -msgid "You are of course welcome to select another license." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:192 -#: ../../tutorials/installable-code.md:22 -#: ../../tutorials/installable-code.md:411 -#: ../../tutorials/installable-code.md:502 ../../tutorials/intro.md: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:193 -msgid "" -"I think we'd need the SPDX license options here if they want to chose " -"bsd-3 for instance" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:196 -msgid "Step 4: Close the config file and run `hatch config show`" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:198 -msgid "" -"Once you have completed the steps above run the following command in your" -" shell." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:200 -msgid "`hatch config show`" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:202 -msgid "" -"`hatch config show` will print out the contents of your `config.toml` " -"file in your shell. look at the values and ensure that your name, email " -"is set. Also make sure that `tests=false`." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:206 -msgid "Hatch features" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:208 -msgid "" -"Hatch offers a suite of features that will make creating, publishing and " -"maintaining your Python package easier." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:211 -msgid "Comparison to other tools" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:213 -msgid "" -"[We compared Hatch to several of the other popular packaging tools in the" -" ecosystem including flit, pdm and poetry. Learn more here](package-" -"features)" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:216 -msgid "[More on Hatch here](hatch)" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:218 -msgid "A few features that Hatch offers" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:220 -msgid "" -"it will convert metadata stored in a `setup.py` or `setup.cfg` file to a " -"pyproject.toml file for you (see [Migrating setup.py to pyproject.toml " -"using Hatch](setup-py-to-pyproject-toml.md ))" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:222 -msgid "" -"It will help you by storing configuration information for publishing to " -"PyPI after you've entered it once." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:224 -msgid "Use `hatch -h` to see all of the available commands." -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:226 -msgid "What's next" -msgstr "" - -#: ../../tutorials/get-to-know-hatch.md:228 -msgid "" -"In the next lesson you'll learn how to package and make your code " -"installable using Hatch." -msgstr "" - -#: ../../tutorials/installable-code.md:6 -msgid "Make your Python code installable" -msgstr "" - -#: ../../tutorials/installable-code.md:8 -msgid "What we previously covered" -msgstr "" - -#: ../../tutorials/installable-code.md:9 -msgid "" -"[In the previous lesson](intro), you learned about what a Python package " -"is. You also learned about the [benefits of creating a Python package" -"](package-benefits)." -msgstr "" - -#: ../../tutorials/installable-code.md:13 -msgid "" -"Your next step in our packaging tutorial series is to create a Python " -"package that is installable both locally and remotely from a website such" -" as GitHub (or GitLab). The package that you create in this lesson will " -"have the bare minimum elements needed to be installable into a Python " -"environment." -msgstr "" - -#: ../../tutorials/installable-code.md:18 -msgid "" -"Making your code installable is an important steps towards creating a " -"full Python package that is directly installable from PyPI." -msgstr "" - -#: ../../tutorials/installable-code.md:23 -msgid "" -"Is it clear where to add commands? Bash vs. Python console Bash vs. Zsh " -"is different" -msgstr "" - -#: ../../tutorials/installable-code.md:25 -msgid "Does this lesson run as expected on windows and mac?" -msgstr "" - -#: ../../tutorials/installable-code.md:26 -msgid "" -"ADD: note about what makes something \"package worthy\", with a common " -"misconception being that a package should be production-ready code that's" -" valuable to a broad audience. this may not be a pervasive misconception " -"in Python, but a quick break-out with an explanation of what a package " -"can consist of would be helpful." -msgstr "" - -#: ../../tutorials/installable-code.md:31 -msgid "" -"Diagram showing the basic steps to creating an installable package. There" -" are 4 boxes with arrows pointing towards the right. The boxes read, your" -" code, create package structure, add metadata to pyproject.toml and pip " -"install package." -msgstr "" - -#: ../../tutorials/installable-code.md:33 -msgid "" -"A basic installable package needs a few things: code, a [specific package" -" file structure](https://www.pyopensci.org/python-package-guide/package-" -"structure-code/python-package-structure.html) and a `pyproject.toml` " -"containing your package's name and version. Once you have these items in " -"the correct directory structure, you can pip install your package into " -"any environment on your computer. You will learn how to create a basic " -"installable package in this lesson." -msgstr "" - -#: ../../tutorials/installable-code.md:37 -msgid "About this lesson" -msgstr "" - -#: ../../tutorials/installable-code.md:43 -msgid "" -"How to make your code installable into any Python environment both " -"locally and from GitHub" -msgstr "" - -#: ../../tutorials/installable-code.md:44 -msgid "" -"How to create a basic `pyproject.toml` file that includes package " -"dependencies and metadata. This file is required to make your package " -"installable." -msgstr "" - -#: ../../tutorials/installable-code.md:45 -msgid "" -"How to declare a [build backend](build_backends) which will be used to " -"[build](build-package) and install your package" -msgstr "" - -#: ../../tutorials/installable-code.md:46 -msgid "How to install your package in editable mode for interactive development" -msgstr "" - -#: ../../tutorials/installable-code.md:48 -msgid "**What you need to complete this lesson**" -msgstr "" - -#: ../../tutorials/installable-code.md:50 -msgid "" -"To complete this lesson you will need a local Python environment and " -"shell on your computer. You will also need to have [Hatch installed](get-" -"to-know-hatch)." -msgstr "" - -#: ../../tutorials/installable-code.md:53 -msgid "" -"If you are using Windows or are not familiar with Shell, you may want to " -"check out the Carpentries shell lesson[^shell-lesson]. Windows users will" -" likely need to configure a tool for any Shell and git related steps." -msgstr "" - -#: ../../tutorials/installable-code.md:55 -msgid "**What comes next**" -msgstr "" - -#: ../../tutorials/installable-code.md:57 -msgid "In the upcoming lessons you will learn how to:" -msgstr "" - -#: ../../tutorials/installable-code.md:59 -msgid "[Publish your package to PyPI](publish-pypi)" -msgstr "" - -#: ../../tutorials/installable-code.md:60 -msgid "Add a README file to your package to support community use" -msgstr "" - -#: ../../tutorials/installable-code.md:61 -msgid "" -"Add additional project metadata to your package to support PyPI " -"publication" -msgstr "" - -#: ../../tutorials/installable-code.md:67 -msgid "" -"This diagram has two smaller boxes with arrows pointing to the right to a" -" Python environment. The small boxes read your-package and pip install " -"package. The environment box on the right reads - your Python " -"environment. It them lists your-package along with a few other core " -"packages such as Matplotlib, NumPy, Pandas, Xarray and GeoPandas." -msgstr "" - -#: ../../tutorials/installable-code.md:69 -msgid "" -"Making your code installable is the first step towards creating a " -"publishable Python package. Once your code is installable, it is a Python" -" package and can be added to any Python environment on your computer and " -"imported in the same way that you might import a package such as Pandas " -"or GeoPandas. If your code is on GitHub or GitLab you can also install it" -" directly from there." -msgstr "" - -#: ../../tutorials/installable-code.md:74 -msgid "About the Python package directory structure" -msgstr "" - -#: ../../tutorials/installable-code.md:76 -msgid "" -"To make your Python code installable you need to create a specific " -"directory structure with the following elements:" -msgstr "" - -#: ../../tutorials/installable-code.md:78 -msgid "A `pyproject.toml` file." -msgstr "" - -#: ../../tutorials/installable-code.md:79 -msgid "A specific directory structure." -msgstr "" - -#: ../../tutorials/installable-code.md:80 -msgid "Some code." -msgstr "" - -#: ../../tutorials/installable-code.md:81 -msgid "An `__init__.py` file in your code directory." -msgstr "" - -#: ../../tutorials/installable-code.md:83 -msgid "The directory structure you’ll create in this lesson will look like this:" -msgstr "" - -#: ../../tutorials/installable-code.md:95 -msgid "About the basic package directory structure" -msgstr "" - -#: ../../tutorials/installable-code.md:97 -msgid "Notice a few things about the above layout:" -msgstr "" - -#: ../../tutorials/installable-code.md:99 -msgid "" -"Your package code lives within a `src/packagename` directory. We suggest " -"that you use `src` (short for **source code**) directory as it [ensures " -"that you are running tests on the installed version of your " -"code](https://www.pyopensci.org/python-package-guide/package-structure-" -"code/python-package-structure.html#the-src-layout-and-testing)." -msgstr "" - -#: ../../tutorials/installable-code.md:100 -msgid "" -"Within the `src` directory you have a package directory called " -"`pyospackage`. Use the name of your package for that directory name. This" -" will be the name for importing your package in Python code once " -"installed." -msgstr "" - -#: ../../tutorials/installable-code.md:101 -msgid "" -"In your package directory, you have an `__init__.py` file and all of your" -" Python modules. You will learn more about the `__init__.py` file below." -msgstr "" - -#: ../../tutorials/installable-code.md:102 -msgid "The `pyproject.toml` file lives at the root directory of your package." -msgstr "" - -#: ../../tutorials/installable-code.md:103 -msgid "" -"The name of the root directory for the package is **pyospackage** which " -"is the name of the package. This is not a requirement but you will often " -"see that the GitHub / GitLab repository and the root directory name are " -"the same as the package name." -msgstr "" - -#: ../../tutorials/installable-code.md:105 -msgid "What is an `__init__.py` file?" -msgstr "" - -#: ../../tutorials/installable-code.md:107 -msgid "" -"The `__init__.py` file tells Python that a directory should be treated as" -" a Python package. As such, a directory with an `__init__.py` file can be" -" imported directly into Python. The `__init__.py` file does not need to " -"contain any code in order for Python to recognize it; it can be empty." -msgstr "" - -#: ../../tutorials/installable-code.md:111 -msgid "" -"For example, following the file structure example above which has an " -"`__init__.py` file within it, you can run:" -msgstr "" - -#: ../../tutorials/installable-code.md:117 ../../tutorials/pyproject-toml.md:48 -msgid "What is a pyproject.toml file?" -msgstr "" - -#: ../../tutorials/installable-code.md:119 -msgid "The **pyproject.toml** file is:" -msgstr "" - -#: ../../tutorials/installable-code.md:121 -msgid "" -"Where you define your project’s metadata (including its name, authors, " -"license, etc)" -msgstr "" - -#: ../../tutorials/installable-code.md:122 -msgid "Where you define dependencies (the packages that it depends on)" -msgstr "" - -#: ../../tutorials/installable-code.md:123 -msgid "" -"Used to specify and configure what build backend you want to use to " -"[build your package](../package-structure-code/python-package-" -"distribution-files-sdist-wheel)." -msgstr "" - -#: ../../tutorials/installable-code.md:125 -msgid "" -"After the `__init__.py` and `pyproject.toml` files have been added, your " -"package can be built and distributed as an installable Python package " -"using tools such as pip. Note that the `pyproject.toml` file needs to " -"have a few basic items defined for the package to be installable " -"including:" -msgstr "" - -#: ../../tutorials/installable-code.md:131 -msgid "The `build-backend` that you want to use," -msgstr "" - -#: ../../tutorials/installable-code.md:132 -msgid "The project `name` and `version`." -msgstr "" - -#: ../../tutorials/installable-code.md:134 -msgid "Why the pyproject.toml file is important" -msgstr "" - -#: ../../tutorials/installable-code.md:138 -msgid "" -"The `pyproject.toml` file replaces some of the functionality of both the " -"`setup.py` file and `setup.cfg` files. If you try to pip install a " -"package with no `pyproject.toml` you will get the following error:" -msgstr "" - -#: ../../tutorials/installable-code.md:150 -msgid "Note about `setup.py`" -msgstr "" - -#: ../../tutorials/installable-code.md:154 -msgid "" -"If your project already defines a `setup.py` file, Hatch can be used to " -"automatically create the `pyproject.toml`." -msgstr "" - -#: ../../tutorials/installable-code.md:155 -msgid "" -"See [Using Hatch to Migrate setup.py to a pyproject.toml ](setup-py-to-" -"pyproject-toml.md)" -msgstr "" - -#: ../../tutorials/installable-code.md:161 -msgid "Time to create your Python package!" -msgstr "" - -#: ../../tutorials/installable-code.md:163 -msgid "" -"Now that you understand the basics of the Python package directory " -"structure, and associated key files (`__init__.py` and `pyproject.toml`)," -" it's time to create your Python package! Below you will create a " -"directory structure similar to the structure described above using Hatch." -msgstr "" - -#: ../../tutorials/installable-code.md:167 -msgid "Step 1: Set Up the Package Directory Structure" -msgstr "" - -#: ../../tutorials/installable-code.md:169 -msgid "Open your shell or preferred terminal." -msgstr "" - -#: ../../tutorials/installable-code.md:170 -msgid "" -"Use the shell `cd` command to navigate in your shell to the location " -"where you'd like your package directory to live. Hatch will create the " -"package directory for you" -msgstr "" - -#: ../../tutorials/installable-code.md:171 -msgid "Choose a name for your package. The name should:" -msgstr "" - -#: ../../tutorials/installable-code.md:172 -msgid "Have no spaces (*Required*)" -msgstr "" - -#: ../../tutorials/installable-code.md:173 -msgid "" -"Use all lowercase characters (*Recommended*). For this tutorial we will " -"use `pyospackage`." -msgstr "" - -#: ../../tutorials/installable-code.md:174 -msgid "" -"Only use letter and the characters _ or - in the name. This means that " -"the name `pyos*package` is not an acceptable name. However, the names " -"`pyos_package` or `pyos-package` both are ok" -msgstr "" - -#: ../../tutorials/installable-code.md:176 -msgid "Hatch and project names" -msgstr "" - -#: ../../tutorials/installable-code.md:177 -msgid "" -"Hatch makes some decisions for your project's name when you run `hatch " -"new`" -msgstr "" - -#: ../../tutorials/installable-code.md:179 -msgid "These include using:" -msgstr "" - -#: ../../tutorials/installable-code.md:180 -msgid "dashes for the top level directory" -msgstr "" - -#: ../../tutorials/installable-code.md:181 -msgid "dashes for the project name in the pyproject.toml" -msgstr "" - -#: ../../tutorials/installable-code.md:182 -msgid "underscores for the package directory name" -msgstr "" - -#: ../../tutorials/installable-code.md:196 -msgid "If you use a name with underscores, Hatch will return the same thing:" -msgstr "" - -#: ../../tutorials/installable-code.md:209 -msgid "" -"In both of the examples above the project name in the pyproject.toml file" -" that hatch creates is `pyos-package`." -msgstr "" - -#: ../../tutorials/installable-code.md:213 -msgid "Next run:" -msgstr "" - -#: ../../tutorials/installable-code.md:228 -msgid "Your final project directory structure should look like this:" -msgstr "" - -#: ../../tutorials/installable-code.md:243 -msgid "Step 2: Add module to your package" -msgstr "" - -#: ../../tutorials/installable-code.md:245 -msgid "" -"A Python module refers to a `.py` file containing the code that you want " -"your package to access and run. Within the `pyospackage` subdirectory, " -"add at least one Python modules (.py files)." -msgstr "" - -#: ../../tutorials/installable-code.md:247 -msgid "" -"If you don't have code already and are just learning how to create a " -"Python package, then create an empty `add_numbers.py` file. You will " -"populate the `add_numbers.py` file with code provided below." -msgstr "" - -#: ../../tutorials/installable-code.md:250 -msgid "Python modules and the `__init__.py` file" -msgstr "" - -#: ../../tutorials/installable-code.md:254 -msgid "" -"When you see the word module, we are referring to a `.py` file containing" -" Python code." -msgstr "" - -#: ../../tutorials/installable-code.md:257 -msgid "" -"The `__init__.py` allows Python to recognize that a directory contains " -"at least one module that may be imported and used in your code. A package" -" can have multiple modules[^python-modules]." -msgstr "" - -#: ../../tutorials/installable-code.md:261 -msgid "Your project directory should now look like this:" -msgstr "" - -#: ../../tutorials/installable-code.md:271 -msgid "Step 3: Add code to your module" -msgstr "" - -#: ../../tutorials/installable-code.md:273 -msgid "" -"If you are following along and making a Python package from scratch then " -"you can add the code below to your `add_numbers.py` module. The function " -"below adds two integers together and returns the result. Notice that the " -"code below has a few features that we will review in future tutorials:" -msgstr "" - -#: ../../tutorials/installable-code.md:275 -msgid "It has a [numpy-style docstring](numpy-docstring)" -msgstr "" - -#: ../../tutorials/installable-code.md:276 -msgid "It uses [typing](type-hints)" -msgstr "" - -#: ../../tutorials/installable-code.md:278 -msgid "" -"Python can support many different docstrings formats depending on the " -"documentation build system you wish to use. The most popular supported " -"formats for documenting Python objects are NumPy Style " -"Docstring[^numpydoc], Google Style Docstring[^googledoc], and the Epytext" -" Style Docstrings[^epytextdoc]." -msgstr "" - -#: ../../tutorials/installable-code.md:280 -msgid "**pyOpenSci recommends using the NumPy Docstring convention.**" -msgstr "" - -#: ../../tutorials/installable-code.md:282 -msgid "" -"If you aren’t familiar with docstrings or typing yet, that is ok. You can" -" review [this page in the pyOpenSci packaging " -"guide](https://www.pyopensci.org/python-package-guide/documentation" -"/write-user-documentation/document-your-code-api-docstrings.html) for an " -"overview of both topics." -msgstr "" - -#: ../../tutorials/installable-code.md:311 -msgid "Step 4: Modify metadata in your `pyproject.toml` file" -msgstr "" - -#: ../../tutorials/installable-code.md:313 -msgid "" -"Next, you will modify some of the metadata (information) that Hatch adds " -"to your `pyproject.toml` file. You are are welcome to copy the file we " -"have in our [example pyospackage GitHub " -"repository](https://github.com/pyOpenSci/pyosPackage)." -msgstr "" - -#: ../../tutorials/installable-code.md:317 -msgid "Brief overview of the TOML file" -msgstr "" - -#: ../../tutorials/installable-code.md:320 -msgid "" -"[The TOML format](https://toml.io/en/) consists of tables and variables. " -"Tables are sections of information denoted by square brackets:" -msgstr "" - -#: ../../tutorials/installable-code.md:322 -msgid "`[this-is-a-table]`." -msgstr "" - -#: ../../tutorials/installable-code.md:324 -msgid "" -"Tables can contain variables within them defined by an variable name and " -"an `=` sign. For instance, a `build-system` table most often holds two " -"(2) variables:" -msgstr "" - -#: ../../tutorials/installable-code.md:327 -msgid "" -"`requires = `, which tells a build tool what tools it needs to install " -"prior to building your package. In this case " -"[hatchling](https://pypi.org/project/hatchling/)" -msgstr "" - -#: ../../tutorials/installable-code.md:329 -msgid "" -"`build-backend = `, which is used to define the specific build-backend " -"name, (in this example we are using `hatchling.build`)." -msgstr "" - -#: ../../tutorials/installable-code.md:338 -msgid "" -"TOML organizes data structures, defining relationships within a " -"configuration file." -msgstr "" - -#: ../../tutorials/installable-code.md:341 -msgid "" -"[Learn more about the pyproject.toml format here.](../package-structure-" -"code/pyproject-toml-python-package-metadata)" -msgstr "" - -#: ../../tutorials/installable-code.md:345 -msgid "" -"You will learn more about the `pyproject.toml` format in the [next lesson" -" when you add additional metadata / information to this file.](pyproject-" -"toml.md)" -msgstr "" - -#: ../../tutorials/installable-code.md:348 -msgid "" -"Open up the `pyproject.toml` file that Hatch created in your favorite " -"text editor. It should look something like the example below." -msgstr "" - -#: ../../tutorials/installable-code.md:390 -msgid "Edit the file as follows:" -msgstr "" - -#: ../../tutorials/installable-code.md:392 -msgid "" -"Delete `dynamic = [\"version\"]`: This sets up dynamic versioning based " -"on tags stored in your git commit history. We will walk through " -"implementing this in a later lesson." -msgstr "" - -#: ../../tutorials/installable-code.md:393 -msgid "" -"Add `version = \"0.1\"` in the place of `dynamic = [\"version\"]` which " -"you just deleted. This sets up manual versioning." -msgstr "" - -#: ../../tutorials/installable-code.md:394 -msgid "Fill in the description if it doesn't already exist." -msgstr "" - -#: ../../tutorials/installable-code.md:404 -msgid "Remove the `[tool.hatch.version]` table from the bottom of the file." -msgstr "" - -#: ../../tutorials/installable-code.md:412 -msgid "" -"When this lesson exists, uncomment this admonition You will learn how to " -"automate defining a package version using git tags in the version and " -"release your package lesson." -msgstr "" - -#: ../../tutorials/installable-code.md:417 -msgid "OPTIONAL: Adjust project classifiers" -msgstr "" - -#: ../../tutorials/installable-code.md:419 -msgid "" -"Hatch by default provides a list of classifiers that define what Python " -"versions your package supports. These classifiers do not in any way " -"impact your package's build and are primarily intended to be used when " -"you publish your package to PyPI." -msgstr "" - -#: ../../tutorials/installable-code.md:424 -msgid "" -"If you don't plan on publishing to PyPI, you can skip this section. " -"However, if you wish, you can clean it up a bit." -msgstr "" - -#: ../../tutorials/installable-code.md:427 -msgid "To begin:" -msgstr "" - -#: ../../tutorials/installable-code.md:429 -msgid "Remove support for Python 3.8" -msgstr "" - -#: ../../tutorials/installable-code.md:430 -msgid "" -"Within the `[project]` table, update `requires-python = \">3.8\"` to " -"`requires-python = \">3.9\"`" -msgstr "" - -#: ../../tutorials/installable-code.md:432 -msgid "" -"Since you are creating a pure Python package in this lesson, you can " -"remove the following classifiers:" -msgstr "" - -#: ../../tutorials/installable-code.md:442 -msgid "Your new pyproject.toml file should now look something like this:" -msgstr "" - -#: ../../tutorials/installable-code.md:477 -msgid "The bare minimum needed in a pyproject.toml file" -msgstr "" - -#: ../../tutorials/installable-code.md:480 -msgid "" -"The core information that you need in a `pyproject.toml` file in order to" -" publish on PyPI is your **package's name** and the **version**. " -"However, we suggest that you flesh out your metadata early on in the " -"`pyproject.toml` file." -msgstr "" - -#: ../../tutorials/installable-code.md:482 -msgid "" -"Once you have your project metadata in the pyproject.toml file, you will " -"rarely update it. In the next lesson you’ll add more metadata and " -"structure to this file." -msgstr "" - -#: ../../tutorials/installable-code.md:486 -msgid "Step 5: Install your package locally" -msgstr "" - -#: ../../tutorials/installable-code.md:488 -msgid "At this point you should have:" -msgstr "" - -#: ../../tutorials/installable-code.md:490 -msgid "A project directory structure with a `pyproject.toml` file at the root" -msgstr "" - -#: ../../tutorials/installable-code.md:491 -msgid "A package directory containing an empty `__init__.py` file and" -msgstr "" - -#: ../../tutorials/installable-code.md:492 -msgid "At least one Python module (e.g. `add_numbers.py`)" -msgstr "" - -#: ../../tutorials/installable-code.md:494 -msgid "You are now ready to install (and build) your Python package!" -msgstr "" - -#: ../../tutorials/installable-code.md:496 -msgid "" -"While you can do this using hatch, we are going to use pip for this " -"lesson, so you can see how to install your tool into your preferred " -"environment." -msgstr "" - -#: ../../tutorials/installable-code.md:498 -msgid "" -"First open your preferred shell (Windows users may be using something " -"like gitbash) and `cd` into your project directory if you are not already" -" there." -msgstr "" - -#: ../../tutorials/installable-code.md:499 -msgid "Activate the Python environment that you wish to use." -msgstr "" - -#: ../../tutorials/installable-code.md:500 -msgid "Run `python -m pip install -e .`" -msgstr "" - -#: ../../tutorials/installable-code.md:503 -msgid "Add this back in when the lesson is published" -msgstr "" - -#: ../../tutorials/installable-code.md:504 -msgid "" -"Activate the Python environment that you wish to use. If you need help " -"with working with virtual environments check out this lesson (add link)." -msgstr "" - -#: ../../tutorials/installable-code.md:530 -msgid "What does `python -m pip install -e .` do?" -msgstr "" - -#: ../../tutorials/installable-code.md:533 -msgid "Let's break down `python -m pip install -e .`" -msgstr "" - -#: ../../tutorials/installable-code.md:535 -msgid "" -"`python -m pip install -e .` installs your package into the current " -"active Python environment in **editable mode** (`-e`). Installing your " -"package in editable mode, allows you to work on your code and then test " -"the updates interactively in your favorite Python interface. One " -"important caveat of editable mode is that every time you update your " -"code, you may need to restart Python." -msgstr "" - -#: ../../tutorials/installable-code.md:540 -msgid "" -"If you wish to install the package regularly (not in editable mode) you " -"can use:" -msgstr "" - -#: ../../tutorials/installable-code.md:543 -msgid "`python -m pip install . `" -msgstr "" - -#: ../../tutorials/installable-code.md:545 -msgid "**Using `python -m` when calling `pip`**" -msgstr "" - -#: ../../tutorials/installable-code.md:547 -msgid "" -"Above, you use`python -m` to call the version of pip installed into your " -"current active environment. `python -m` is important to ensure that you " -"are calling the version of pip installed in your current environment." -msgstr "" - -#: ../../tutorials/installable-code.md:552 -msgid "Look for pyospackage in your environment" -msgstr "" - -#: ../../tutorials/installable-code.md:554 -msgid "" -"Once you have installed your package, you can view it in your current " -"environment. If you are using `venv` or `conda`, `pip` list will allow " -"you to see your current package installations." -msgstr "" - -#: ../../tutorials/installable-code.md:558 -msgid "" -"Note that because pyospackage is installed in editable mode (`-e`) pip " -"will show you the directory path to your project's code" -msgstr "" - -#: ../../tutorials/installable-code.md:586 -msgid "Step 6: Test out your new package" -msgstr "" - -#: ../../tutorials/installable-code.md:588 -msgid "" -"After installing your package, type “python” at the command prompt in " -"your chosen terminal to start a Python session in your active Python " -"environment." -msgstr "" - -#: ../../tutorials/installable-code.md:591 -msgid "You can now import your package and access the `add_num` function." -msgstr "" - -#: ../../tutorials/installable-code.md:603 -msgid "Installing packages from GitHub" -msgstr "" - -#: ../../tutorials/installable-code.md:605 -msgid "" -"If you wish to share your code without publishing to PyPI you can always " -"install packages directly from GitHub using the syntax:" -msgstr "" - -#: ../../tutorials/installable-code.md:612 -msgid "To make your package GitHub installable, you can:" -msgstr "" - -#: ../../tutorials/installable-code.md:614 -msgid "Create a new GitHub repository" -msgstr "" - -#: ../../tutorials/installable-code.md:615 -msgid "" -"Push the contents of the project directory that you created above, to " -"GitHub" -msgstr "" - -#: ../../tutorials/installable-code.md:616 -msgid "" -"Finally install the package from GitHub using the command above. When you" -" use the command above, don't forget to substitute the user, repo, and " -"branch_or_tag with your specific values." -msgstr "" - -#: ../../tutorials/installable-code.md:618 -msgid "" -"For instance below you install the pyospackage from the main branch of " -"the pyOpenSci repository." -msgstr "" - -#: ../../tutorials/installable-code.md:621 -msgid "`python -m pip install git+https://github.com/user/repo.git@branch_or_tag`" -msgstr "" - -#: ../../tutorials/installable-code.md:625 -msgid "Congratulations! You created your first Python package" -msgstr "" - -#: ../../tutorials/installable-code.md:627 -msgid "" -"You did it! You have now created a Python package that you can install " -"into any Python environment." -msgstr "" - -#: ../../tutorials/installable-code.md:630 -msgid "In the upcoming lessons you will:" -msgstr "" - -#: ../../tutorials/installable-code.md:632 -msgid "" -"Learn how to [build and publish your Python package to (test) PyPI" -"](publish-pypi)" -msgstr "" - -#: ../../tutorials/installable-code.md:633 -msgid "Add a README file and LICENSE to your package" -msgstr "" - -#: ../../tutorials/installable-code.md:634 -msgid "" -"Add more metadata to your `pyproject.toml` file to support PyPI " -"publication." -msgstr "" - -#: ../../tutorials/installable-code.md:635 -msgid "learn how to publish to **conda-forge** from **PyPI**." -msgstr "" - -#: ../../tutorials/installable-code.md:637 -msgid "" -"Add a [README file](add-readme.md) and [LICENSE](add-license-coc.md) to " -"your package" -msgstr "" - -#: ../../tutorials/installable-code.md:638 -msgid "" -"[Add more metadata to your `pyproject.toml`](pyproject-toml.md) file to " -"support PyPI publication." -msgstr "" - -#: ../../tutorials/installable-code.md:639 -msgid "" -"[Learn how to build your package distribution](publish-pypi) files " -"(**sdist** and **wheel**) and publish to **test PyPI**." -msgstr "" - -#: ../../tutorials/installable-code.md:640 -msgid "" -"Finally you will learn how to [publish to **conda-forge**](publish-conda-" -"forge) from **PyPI**." -msgstr "" - -#: ../../tutorials/installable-code.md:644 -msgid "[Carpentries shell lesson](https://swcarpentry.github.io/shell-novice/)" -msgstr "" - -#: ../../tutorials/installable-code.md:646 -msgid "" -"[Python module " -"docs](https://docs.python.org/3/tutorial/modules.html#packages)" -msgstr "" - -#: ../../tutorials/installable-code.md:648 -msgid "[Numpy style docs](https://numpydoc.readthedocs.io/en/latest/format.html)" -msgstr "" - -#: ../../tutorials/installable-code.md:647 -msgid "[Google docstring style](https://google.github.io/styleguide/pyguide.html)" -msgstr "" - -#: ../../tutorials/installable-code.md:649 -msgid "[epydoc](https://epydoc.sourceforge.net/epytext.html)" -msgstr "" - -#: ../../tutorials/intro.md:27 ../../tutorials/setup-py-to-pyproject-toml.md:24 -msgid "Get to know Hatch" -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 "" - diff --git a/noxfile.py b/noxfile.py index ee44f29c..4a0ea835 100644 --- a/noxfile.py +++ b/noxfile.py @@ -43,7 +43,7 @@ ## Localization options (translations) # List of languages for which locales will be generated in (/locales/) -LANGUAGES = ["es", "ja"] +LANGUAGES = ["es"] # List of languages that should be built when releasing the guide (docs or docs-test sessions) RELEASE_LANGUAGES = [] From a5d8e4d34439a3abe9d2b849317eb1e6776f5427 Mon Sep 17 00:00:00 2001 From: Tetsuo Koyama Date: Fri, 2 Aug 2024 18:24:53 +0900 Subject: [PATCH 5/8] Preparing the Translation Files for Japanese --- locales/jp/LC_MESSAGES/CONTRIBUTING.po | 435 ++ locales/jp/LC_MESSAGES/TRANSLATING.po | 717 +++ locales/jp/LC_MESSAGES/documentation.po | 2545 ++++++++ locales/jp/LC_MESSAGES/index.po | 483 ++ .../jp/LC_MESSAGES/package-structure-code.po | 5301 ++++++++++++++++ locales/jp/LC_MESSAGES/tests.po | 1002 +++ locales/jp/LC_MESSAGES/tutorials.po | 5536 +++++++++++++++++ 7 files changed, 16019 insertions(+) create mode 100644 locales/jp/LC_MESSAGES/CONTRIBUTING.po create mode 100644 locales/jp/LC_MESSAGES/TRANSLATING.po create mode 100644 locales/jp/LC_MESSAGES/documentation.po create mode 100644 locales/jp/LC_MESSAGES/index.po create mode 100644 locales/jp/LC_MESSAGES/package-structure-code.po create mode 100644 locales/jp/LC_MESSAGES/tests.po create mode 100644 locales/jp/LC_MESSAGES/tutorials.po diff --git a/locales/jp/LC_MESSAGES/CONTRIBUTING.po b/locales/jp/LC_MESSAGES/CONTRIBUTING.po new file mode 100644 index 00000000..8c6af5ff --- /dev/null +++ b/locales/jp/LC_MESSAGES/CONTRIBUTING.po @@ -0,0 +1,435 @@ +# 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-08-02 18:04+0900\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: jp\n" +"Language-Team: jp \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. To " +"\"fork\" a repository in GitHub means to create a copy of the main " +"repository, or repo, that you have complete control over and can modify " +"as you see fit." +msgstr "" + +#: ../../CONTRIBUTING.md:37 +msgid "To fork a repo," +msgstr "" + +#: ../../CONTRIBUTING.md:39 +msgid "Make sure you are logged into GitHub." +msgstr "" + +#: ../../CONTRIBUTING.md:41 +msgid "" +"Go to the repo you would like to fork, in this case the [Python Packaging" +" Guide](https://www.github.com/pyopensci/python-package-guide) repo." +msgstr "" + +#: ../../CONTRIBUTING.md:43 +msgid "" +"In the top right-hand corner of the page there is a 'Fork' button. Click " +"that button. You will be brought to a new page where you will 'Create a " +"new fork'. Feel free to keep all the default inputs and click 'Create " +"fork'. This will create a copy of the repo at " +"`https://github.com//python-package-guide`, where `` " +"is your GitHub username." +msgstr "" + +#: ../../CONTRIBUTING.md:47 +msgid "Contributing via the GitHub website" +msgstr "" + +#: ../../CONTRIBUTING.md:49 +msgid "How to edit a MarkDown file" +msgstr "" + +#: ../../CONTRIBUTING.md:51 +msgid "" +"*__TODO__: This section should show how to use the GitHub interface to " +"edit and previewing a Markdown file.*" +msgstr "" + +#: ../../CONTRIBUTING.md:53 +msgid "How to commit your changes" +msgstr "" + +#: ../../CONTRIBUTING.md:55 +msgid "" +"*__TODO__: This section should show how to commit changes via the GitHub " +"interface.*" +msgstr "" + +#: ../../CONTRIBUTING.md:57 +msgid "Contributing locally on your computer" +msgstr "" + +#: ../../CONTRIBUTING.md:59 +msgid "Clone your forked repository" +msgstr "" + +#: ../../CONTRIBUTING.md:61 +msgid "" +"*__TODO__: This section should show how to clone a repository from GitHub" +" into your computer.*" +msgstr "" + +#: ../../CONTRIBUTING.md:63 +msgid "Create a new branch" +msgstr "" + +#: ../../CONTRIBUTING.md:65 +msgid "*__TODO__: This section should show how to create a new branch.*" +msgstr "" + +#: ../../CONTRIBUTING.md:67 +msgid "Create a virtual environment" +msgstr "" + +#: ../../CONTRIBUTING.md:69 +msgid "" +"*__TODO__: This section should show how to create a virtual environment " +"using venv.*" +msgstr "" + +#: ../../CONTRIBUTING.md:71 +msgid "Install the development dependencies" +msgstr "" + +#: ../../CONTRIBUTING.md:73 +msgid "" +"*__TODO__: This section should show how to install the development " +"dependencies defined in pyproject.toml.*" +msgstr "" + +#: ../../CONTRIBUTING.md:75 +msgid "Commit your changes" +msgstr "" + +#: ../../CONTRIBUTING.md:77 +msgid "" +"*__TODO__: This section should describe how to commit from the command " +"line.*" +msgstr "" + +#: ../../CONTRIBUTING.md:79 +msgid "How to build the guide locally" +msgstr "" + +#: ../../CONTRIBUTING.md:81 +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:83 +msgid "Before you submit your pull request" +msgstr "" + +#: ../../CONTRIBUTING.md:85 +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:87 +msgid "Submitting a pull request with your contribution" +msgstr "" + +#: ../../CONTRIBUTING.md:89 +msgid "How to make a pull request" +msgstr "" + +#: ../../CONTRIBUTING.md:91 +msgid "" +"*__TODO__: This section should describe how to make a pull request in " +"GitHub.*" +msgstr "" + +#: ../../CONTRIBUTING.md:93 +msgid "What happens when you submit a pull request (CI/CD)" +msgstr "" + +#: ../../CONTRIBUTING.md:95 +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:97 +msgid "What to expect from the review process" +msgstr "" + +#: ../../CONTRIBUTING.md:99 +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:101 +msgid "Additional help" +msgstr "" + +#: ../../CONTRIBUTING.md:103 +msgid "How to get help" +msgstr "" + +#: ../../CONTRIBUTING.md:105 +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:107 +msgid "Additional resources" +msgstr "" + +#: ../../CONTRIBUTING.md:109 +msgid "" +"*__TODO__: It should also include links to beginner documentation, like " +"the GitHub docs.*" +msgstr "" + +#: ../../CONTRIBUTING.md:111 +msgid "Annex" +msgstr "" + +#: ../../CONTRIBUTING.md:113 +msgid "Code examples" +msgstr "" + +#: ../../CONTRIBUTING.md:115 +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:119 +msgid "Referencing code in documentation" +msgstr "" + +#: ../../CONTRIBUTING.md:121 +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:124 +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:129 +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:133 +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:136 +msgid "Creating code for documentation" +msgstr "" + +#: ../../CONTRIBUTING.md:138 +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:142 +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:146 +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:150 +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:153 +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:161 +msgid "Example:" +msgstr "" + +#: ../../CONTRIBUTING.md:163 +msgid "Instead of writing example code in markdown like this" +msgstr "" + +#: ../../CONTRIBUTING.md:174 +msgid "The python can be extracted into a `.py` file" +msgstr "" + +#: ../../CONTRIBUTING.md:188 +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:191 +msgid "Instead of writing this" +msgstr "" + +#: ../../CONTRIBUTING.md:203 +msgid "an example could be extracted from an existing toml file" +msgstr "" + diff --git a/locales/jp/LC_MESSAGES/TRANSLATING.po b/locales/jp/LC_MESSAGES/TRANSLATING.po new file mode 100644 index 00000000..85a36658 --- /dev/null +++ b/locales/jp/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-08-02 18:04+0900\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: jp\n" +"Language-Team: jp \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/jp/LC_MESSAGES/documentation.po b/locales/jp/LC_MESSAGES/documentation.po new file mode 100644 index 00000000..c9534283 --- /dev/null +++ b/locales/jp/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-08-02 18:04+0900\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: jp\n" +"Language-Team: jp \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://pyopensci.org/badges/peer-" +"reviewed.svg)](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/jp/LC_MESSAGES/index.po b/locales/jp/LC_MESSAGES/index.po new file mode 100644 index 00000000..d7c8cb33 --- /dev/null +++ b/locales/jp/LC_MESSAGES/index.po @@ -0,0 +1,483 @@ +# 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-08-02 18:04+0900\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: jp\n" +"Language-Team: jp \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" + +#: ../../index.md:283 +msgid "Tutorials" +msgstr "" + +#: ../../index.md:289 +msgid "Packaging" +msgstr "" + +#: ../../index.md:139 ../../index.md:297 +msgid "Documentation" +msgstr "" + +#: ../../index.md:187 ../../index.md:305 +msgid "Tests" +msgstr "" + +#: ../../index.md:305 +msgid "Testing" +msgstr "" + +#: ../../index.md:1 +msgid "pyOpenSci Python Package Guide" +msgstr "" + +#: ../../index.md:3 +msgid "" +"We support the Python tools that scientists need to create open science " +"workflows." +msgstr "" + +#: ../../index.md:20 +msgid "" +"![GitHub release (latest by " +"date)](https://img.shields.io/github/v/release/pyopensci/python-package-" +"guide?color=purple&display_name=tag&style=plastic) " +"[![](https://img.shields.io/github/stars/pyopensci/python-package-" +"guide?style=social)](https://github.com/pyopensci/contributing-guide) " +"[![DOI](https://zenodo.org/badge/556814582.svg)](https://zenodo.org/badge/latestdoi/556814582)" +msgstr "" + +#: ../../index.md:20 +msgid "GitHub release (latest by date)" +msgstr "" + +#: ../../index.md:20 +msgid "DOI" +msgstr "" + +#: ../../index.md:27 +msgid "About this guide" +msgstr "" + +#: ../../index.md:29 +msgid "" +"Image with the pyOpenSci flower logo in the upper right hand corner. The " +"image shows the packaging lifecycle. The graphic shows a high level " +"overview of the elements of a Python package. the inside circle has 5 " +"items - user documentation, code/api, test suite, contributor " +"documentation, project metadata / license / readme. In the middle of the " +"circle is says maintainers and has a small icon with people. on the " +"outside circle there is an arrow and it says infrastructure." +msgstr "" + +#: ../../index.md:35 +msgid "This guide will help you:" +msgstr "" + +#: ../../index.md:37 +msgid "Learn how to create a Python package from start to finish" +msgstr "" + +#: ../../index.md:38 +msgid "Understand the broader Python packaging tool ecosystem" +msgstr "" + +#: ../../index.md:39 +msgid "Navigate and make decisions around tool options" +msgstr "" + +#: ../../index.md:40 +msgid "Understand all of the pieces of creating and maintaining a Python package" +msgstr "" + +#: ../../index.md:42 +msgid "" +"You will also find best practice recommendations and curated lists of " +"community resources surrounding packaging and package documentation." +msgstr "" + +#: ../../index.md:46 +msgid "Todo" +msgstr "" + +#: ../../index.md:47 +msgid "TODO: change the navigation of docs to have a" +msgstr "" + +#: ../../index.md:49 +msgid "user documentation contributor / maintainer documentation" +msgstr "" + +#: ../../index.md:51 +msgid "development guide" +msgstr "" + +#: ../../index.md:52 +msgid "contributing guide" +msgstr "" + +#: ../../index.md:54 +msgid "Community docs" +msgstr "" + +#: ../../index.md:55 +msgid "readme, coc, license" +msgstr "" + +#: ../../index.md:57 +msgid "Publish your docs" +msgstr "" + +#: ../../index.md:59 +msgid "_new_ Tutorial Series: Create a Python Package" +msgstr "" + +#: ../../index.md:61 +msgid "" +"The first round of our community-developed, how to create a Python " +"package tutorial series for scientists is complete! Join our community " +"review process or watch development of future tutorials in our [Github " +"repo here](https://github.com/pyOpenSci/python-package-guide)." +msgstr "" + +#: ../../index.md:71 +msgid "✿ Create a Package Tutorials ✿" +msgstr "" + +#: ../../index.md:75 +msgid "[What is a Python package?](/tutorials/intro)" +msgstr "" + +#: ../../index.md:76 +msgid "[Make your code installable](/tutorials/installable-code)" +msgstr "" + +#: ../../index.md:77 +msgid "[Publish your package to (test) PyPI](/tutorials/publish-pypi)" +msgstr "" + +#: ../../index.md:78 +msgid "[Publish your package to conda-forge](/tutorials/publish-conda-forge)" +msgstr "" + +#: ../../index.md:83 +msgid "✿ Package Metadata Tutorials ✿" +msgstr "" + +#: ../../index.md:87 +msgid "[How to add a README file](/tutorials/add-readme)" +msgstr "" + +#: ../../index.md:88 +msgid "" +"[How to add metadata to a pyproject.toml file for publication to " +"PyPI.](/tutorials/pyproject-toml.md)" +msgstr "" + +#: ../../index.md:93 +msgid "✿ Packaging Tool Tutorials ✿" +msgstr "" + +#: ../../index.md:97 +msgid "[Introduction to Hatch](/tutorials/get-to-know-hatch)" +msgstr "" + +#: ../../index.md:102 +msgid "Python Packaging for Scientists" +msgstr "" + +#: ../../index.md:104 +msgid "" +"Learn about Python packaging best practices. You will also get to know " +"the the vibrant ecosystem of packaging tools that are available to help " +"you with your Python packaging needs." +msgstr "" + +#: ../../index.md:113 +msgid "✨ Create your package ✨" +msgstr "" + +#: ../../index.md:117 +msgid "[Package file structure](/package-structure-code/python-package-structure)" +msgstr "" + +#: ../../index.md:118 +msgid "" +"[Package metadata / pyproject.toml](package-structure-code/pyproject-" +"toml-python-package-metadata.md)" +msgstr "" + +#: ../../index.md:119 +msgid "" +"[Build your package (sdist / wheel)](package-structure-code/python-" +"package-distribution-files-sdist-wheel.md)" +msgstr "" + +#: ../../index.md:120 +msgid "[Declare dependencies](package-structure-code/declare-dependencies.md)" +msgstr "" + +#: ../../index.md:121 +msgid "" +"[Navigate the packaging tool ecosystem](package-structure-code/python-" +"package-build-tools.md)" +msgstr "" + +#: ../../index.md:122 +msgid "" +"[Non pure Python builds](package-structure-code/complex-python-package-" +"builds.md)" +msgstr "" + +#: ../../index.md:127 +msgid "✨ Publish your package ✨" +msgstr "" + +#: ../../index.md:131 +msgid "" +"Gain a better understanding of the Python packaging ecosystem Learn about" +" best practices for:" +msgstr "" + +#: ../../index.md:134 +msgid "" +"[Package versioning & release](/package-structure-code/python-package-" +"versions.md)" +msgstr "" + +#: ../../index.md:135 +msgid "" +"[Publish to PyPI & Conda-forge](/package-structure-code/publish-python-" +"package-pypi-conda.md)" +msgstr "" + +#: ../../index.md:148 +msgid "✨ Write The Docs ✨" +msgstr "" + +#: ../../index.md:151 +msgid "" +"[Create documentation for your users](/documentation/write-user-" +"documentation/intro)" +msgstr "" + +#: ../../index.md:152 +msgid "" +"[Core files to include in your package repository](/documentation" +"/repository-files/intro)" +msgstr "" + +#: ../../index.md:153 +msgid "" +"[Write tutorials to show how your package is used](/documentation/write-" +"user-documentation/create-package-tutorials)" +msgstr "" + +#: ../../index.md:158 +msgid "✨ Developer Docs ✨" +msgstr "" + +#: ../../index.md:161 +msgid "" +"[Create documentation for collaborating developers](/documentation" +"/repository-files/contributing-file)" +msgstr "" + +#: ../../index.md:162 +msgid "" +"[Write a development guide](/documentation/repository-files/development-" +"guide)" +msgstr "" + +#: ../../index.md:167 +msgid "✨ Document For A Community ✨" +msgstr "" + +#: ../../index.md:170 +msgid "" +"[Writing a README file](/documentation/repository-files/readme-file-best-" +"practices)" +msgstr "" + +#: ../../index.md:171 +msgid "" +"[Set norms with a Code of Conduct](/documentation/repository-files/code-" +"of-conduct-file)" +msgstr "" + +#: ../../index.md:172 +msgid "[License your package](/documentation/repository-files/license-files)" +msgstr "" + +#: ../../index.md:177 +msgid "✨ Publish Your Docs ✨" +msgstr "" + +#: ../../index.md:180 +msgid "[How to publish your docs](/documentation/hosting-tools/intro)" +msgstr "" + +#: ../../index.md:181 +msgid "[Using Sphinx](/documentation/hosting-tools/intro)" +msgstr "" + +#: ../../index.md:182 +msgid "" +"[Markdown, MyST, and ReST](/documentation/hosting-tools/myst-markdown-" +"rst-doc-syntax)" +msgstr "" + +#: ../../index.md:183 +msgid "" +"[Host your docs on Read The Docs or Github Pages](/documentation/hosting-" +"tools/publish-documentation-online)" +msgstr "" + +#: ../../index.md:189 +msgid "" +"*We are actively working on this section. [Follow development " +"here.](https://github.com/pyOpenSci/python-package-guide)*" +msgstr "" + +#: ../../index.md:197 +msgid "✨ Tests for your Python package ✨" +msgstr "" + +#: ../../index.md:200 +msgid "[Intro to testing](tests/index.md)" +msgstr "" + +#: ../../index.md:201 +msgid "[Write tests](tests/write-tests)" +msgstr "" + +#: ../../index.md:202 +msgid "[Types of tests](tests/test-types)" +msgstr "" + +#: ../../index.md:207 +msgid "✨ Run your tests ✨" +msgstr "" + +#: ../../index.md:210 +msgid "[Run tests locally](tests/run-tests)" +msgstr "" + +#: ../../index.md:211 +msgid "[Run tests in CI](tests/tests-ci)" +msgstr "" + +#: ../../index.md:215 +msgid "Contributing" +msgstr "" + +#: ../../index.md:225 +msgid "✨ Code style & Format ✨" +msgstr "" + +#: ../../index.md:230 +msgid "[Code style](package-structure-code/code-style-linting-format.md)" +msgstr "" + +#: ../../index.md:235 +msgid "✨ Want to contribute? ✨" +msgstr "" + +#: ../../index.md:240 +msgid "" +"We welcome contributions to this guide. Learn more about how you can " +"contribute." +msgstr "" + +#: ../../index.md:246 +msgid "" +"xkcd comic showing a stick figure on the ground and one in the air. The " +"one on the ground is saying. `You're flying! how?` The person in the air" +" replies `Python!` Below is a 3 rectangle comic with the following text " +"in each box. box 1 - I learned it last night. Everything is so simple. " +"Hello world is just print hello world. box 2 - the person on the ground " +"says - come join us programming is fun again. it's a whole new world. But" +" how are you flying? box 3 - the person flying says - i just typed import" +" antigravity. I also sampled everything in the medicine cabinet. But i " +"think this is the python. the person on the ground is saying - that's it?" +msgstr "" + +#: ../../index.md:252 +msgid "A community-created guidebook" +msgstr "" + +#: ../../index.md:254 +msgid "" +"Every page in this guidebook goes through an extensive community review " +"process. To ensure our guidebook is both beginner-friendly and accurate, " +"we encourage reviews from a diverse set of pythonistas and scientists " +"with a wide range of skills and expertise." +msgstr "" + +#: ../../index.md:257 +msgid "View guidebook contributors" +msgstr "" + +#: ../../index.md:265 +msgid "Who this guidebook is for" +msgstr "" + +#: ../../index.md:267 +msgid "" +"This guidebook is for anyone interested in learning more about Python " +"packaging. It is beginner-friendly and will provide:" +msgstr "" + +#: ../../index.md:269 +msgid "Beginning-to-end guidance on creating a Python package." +msgstr "" + +#: ../../index.md:270 +msgid "" +"Resources to help you navigate the Python packaging ecosystem of tools " +"and approaches to packaging." +msgstr "" + +#: ../../index.md:271 +msgid "" +"A curated list of resources to help you get your package into documented," +" usable and maintainable shape." +msgstr "" + +#: ../../index.md:273 +msgid "Where this guide is headed" +msgstr "" + +#: ../../index.md:275 +msgid "" +"If you have ideas of things you'd like to see here clarified in this " +"guide, [we invite you to open an issue on " +"GitHub.](https://github.com/pyOpenSci/python-package-guide/issues)." +msgstr "" + +#: ../../index.md:278 +msgid "" +"If you have questions about our peer review process or packaging in " +"general, you are welcome to use our [pyOpenSci Discourse " +"forum](https://pyopensci.discourse.group/)." +msgstr "" + +#: ../../index.md:280 +msgid "" +"This is a living guide that is updated as tools and best practices evolve" +" in the Python packaging ecosystem. We will be adding new content over " +"the next year." +msgstr "" + diff --git a/locales/jp/LC_MESSAGES/package-structure-code.po b/locales/jp/LC_MESSAGES/package-structure-code.po new file mode 100644 index 00000000..fe7f0e4a --- /dev/null +++ b/locales/jp/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-08-02 18:04+0900\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: jp\n" +"Language-Team: jp \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:182 +msgid "Python file `temporal.py` imports after `isort` has been run" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:189 +msgid "Ruff" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:191 +msgid "" +"[Ruff](https://docs.astral.sh/ruff/) is a new addition to the code " +"quality ecosystem, gaining some traction since its release. `ruff` is " +"both a linter and a code formatter for Python, aiming to replace several " +"tools behind a single interface. As such, `ruff` can be used at a " +"replacement of all other tools mentioned here, or in complement to some " +"of them." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:197 +msgid "" +"`ruff` has some interesting features that distinguish it from other " +"linters:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:199 +msgid "Linter configuration in `pyproject.toml`" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:200 +msgid "Several hundred rules included, many of which are automatically fixable" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:201 +msgid "" +"Rules explanation, see [F403](https://docs.astral.sh/ruff/rules" +"/undefined-local-with-import-star/) for an example" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:202 +msgid "" +"Fast execution time, makes a quick feedback loop possible even on large " +"projects." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:204 +msgid "" +"Here is a simple configuration to get started with `ruff`. It would go " +"into your `pyproject.toml`:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:212 +msgid "" +"Depending on your project, you might want to add the following to sort " +"imports correctly:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:219 +msgid "How to use code formatter in your local workflow" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:221 +msgid "Linters, code formatters and your favorite coding tools" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:223 +msgid "" +"Linters can be run as a command-line tool as shown above. They also can " +"be run within your favorite coding tool (e.g. VScode, pycharm, etc). For " +"example, you might prefer to have tools like Black and isort run when you" +" save a file. In some editors you can also setup shortcuts that run your " +"favorite code format tools on demand." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:229 +msgid "Use pre-commit hooks to run code formatters and linters on commits" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:231 +msgid "You can also setup a `pre-commit hook` in your Python package repository." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:233 +msgid "" +"A pre-commit hook is a tool that allows an action (or actions) to be " +"triggered when you apply a commit to your git repository." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:236 +msgid "Pre-commit hook example workflow" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:238 +msgid "The precommit workflow looks like this: You type and run:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:241 +msgid "`git commit -m \"message here\"` at the command line" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:243 +msgid "" +"Once you hit return, pre-commit will run any tools that you have " +"configured in a **.pre-commit-config.yaml** file." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:245 +msgid "" +"If the tools configured in the pre-commit hook run successfully without " +"making changes or finding errors in your code, the commit will be applied" +" to the repository." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:249 +msgid "" +"If the tools configured in the hook find errors in your files, the commit" +" will NOT be applied to the repository. Remember from the discussion " +"above that a code formatter like Black will run and reformat your code. A" +" linter like _flake8_ will provide you with some output that details " +"where there are syntax issues in your code. You will then need to fix " +"those issues, manually." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:256 +msgid "" +"Once all of the fixes are applied you can re-add (stage) the files to be " +"commit. And re-run your commit." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:260 +msgid "Diagram showing the steps of a pre-commit workflow from left to right." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:262 +msgid "" +"The pre-commit workflow begins with you adding files that have changes to" +" be staged in git. Next, you'd run git commit. when you run git commit, " +"the pre-commit hooks will then run. In this example, Black, the code " +"formatter and flake8, a linter both run. If all of the files pass Black " +"and flake8 checks, then your commit will be recorded. If they don't, the " +"commit is canceled. You will have to fix any flake8 issues, and then re-" +"add / stage the files to be committed. [_Image " +"Source_](https://ljvmiranda921.github.io/notebook/2018/06/21/precommits-" +"using-black-and-flake8/*)" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:275 +msgid "" +"If have a Python code-base and multiple maintainers actively working on " +"the code, and you intend to run a tool like Black, be sure to coordinate " +"across your team. An initial commit that applies Black to your entire " +"package will likely change a significant amount of your code. This could " +"lead to merge conflicts on open and new PR's before the new changes are " +"merged." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:282 +msgid "General pre commit checks" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:284 +msgid "" +"In addition to calling tools, Pre-commit also has a suite of [built in " +"format hooks](https://github.com/pre-commit/pre-commit-hooks#hooks-" +"available) that you can call. Some, such as trailing-whitespace can be " +"also useful to add to your pre-commit workflow to ensure clean, " +"streamlined code files." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:289 +msgid "" +"An example pre-commit-config.yaml file is below with examples of how this" +" is all setup." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:292 +msgid "Pre-commit.ci" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:294 +msgid "" +"[Pre-commit.ci](https://pre-commit.ci) is a bot that may become your new " +"best friend. This bot, when setup on a repo can be configured to do the " +"following:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:297 +msgid "It will check every pull request using all of the pre-commit hook setting" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:298 +msgid "" +"If you wish, it will also submit a pull request to your repo with pre-" +"commit fixes, saving you, and new contributors the time of reformatting a" +" pr that has format issues." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:301 +msgid "You can also call the bot on any pull request to run / and fix the code." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:303 +msgid "" +"The pre-commit.ci bot uses the same pre-commit-config.yaml file that you " +"use to setup pre-commit locally." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:306 +msgid "Setting up a bot like this can be valuable because:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:308 +msgid "" +"It can make is easier for maintainers as they no longer have to worry at " +"allows about fixing code format. The bot will do the work for them." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:310 +msgid "" +"It can make it easier for new comers as they never have to setup pre-" +"commit locally or worry about linting their code. They can even make " +"small fixes to the code directly on GitHub without worry." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:312 +msgid "Setting up a git pre-commit hook" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:314 +msgid "To setup pre-commit locally, you need to do 3 things:" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:316 +msgid "" +"Install pre-commit (and include it as a development requirement in your " +"repository)" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:326 +msgid "" +"Create a .pre-commit-config.yaml file in the root of your package " +"directory." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:328 +msgid "" +"Below is an example **.pre-commit-cofig.yaml** file that can be used to " +"setup the pre-commit hook and the pre-commit.ci bot if you chose to " +"implement that too." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:336 +msgid "" +"This file specifies a hook that will be triggered automatically before " +"each `git commit`, in this case, it specifies a `flake8` using version " +"`6.0.0`." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:339 +msgid "" +"Install your pre-commit hook(s) using `pre-commit install`. This will " +"install all of the hooks specified in the pre-commit yaml file into your " +"environment." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:341 +msgid "" +"Once you have done the above, you are ready to start working on your " +"code. Pre-commit will run every time you run `git commit`." +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:344 +msgid "Summary" +msgstr "" + +#: ../../package-structure-code/code-style-linting-format.md:346 +msgid "" +"pyOpenSci suggests setting up a linter and a code styler for your " +"package, regardless of whether you use pre-commit hooks, CI or other " +"infrastructure to manage code format. Setting up these tools will give " +"you automatic feedback about your code's structure as you (or a " +"contributor) write it. And using a tool like black that format code for " +"you, reduce effort that you need to make surrounding decisions around " +"code format and style." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:1 +msgid "Complex Python package builds" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:3 +msgid "" +"This guide is focused on packages that are either pure-python or that " +"have a few simple extensions in another language such as C or C++." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:6 +msgid "" +"In the future, we want to provide resources for packaging workflows that " +"require more complex builds. If you have questions about these types of " +"package, please [add a question to our " +"discourse](https://pyopensci.discourse.group/) or open an [issue about " +"this guide specifically in the GitHub repo for this " +"guide](https://github.com/pyOpenSci/python-package-guide/issues). There " +"are many nuances to building and distributing Python packages that have " +"compiled extensions requiring non-Python dependencies at build time. For " +"an overview and thorough discussion of these nuances, please see [this " +"site.](https://pypackaging-native.github.io/)" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:8 +msgid "Pure Python Packages vs. packages with extensions in other languages" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:10 +msgid "" +"You can classify Python package complexity into three general categories." +" These categories can in turn help you select the correct package " +"frontend and backend tools." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:14 +msgid "" +"**Pure-python packages:** these are packages that only rely on Python to " +"function. Building a pure Python package is simpler. As such, you can " +"chose a tool below that has the features that you want and be done with " +"your decision!" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:16 +msgid "" +"**Python packages with non-Python extensions:** These packages have " +"additional components called extensions written in other languages (such " +"as C or C++). If you have a package with non-Python extensions, then you " +"need to select a build backend tool that allows additional build steps " +"needed to compile your extension code. Further, if you wish to use a " +"frontend tool to support your workflow, you will need to select a tool " +"that supports additional build setups. We suggest that you chose build " +"tool that supports custom build steps like Hatch." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:18 +msgid "" +"**Python packages that have extensions written in different languages " +"(e.g. Fortran and C++) or that have non Python dependencies that are " +"difficult to install (e.g. GDAL)** These packages often have complex " +"build steps (more complex than a package with just a few C extensions for" +" instance). As such, these packages require tools such as [scikit-" +"build](https://scikit-build.readthedocs.io/en/latest/) or [meson-" +"python](https://mesonbuild.com/Python-module.html) to build. NOTE: you " +"can use meson-python with PDM." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:21 +msgid "Mixing frontend and backend projects" +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:23 +msgid "" +"It is sometimes necessary or desirable to use a build frontend with an " +"alternative build-backend. This is because some frontends do not have a " +"default backend (`build`), and this choice is placed on the maintainer. " +"Other backends (`hatch`) have a preferred backend (`hatchling`) but allow" +" the maintainer to migrate to another, while some backends (`poetry`) " +"only work with a single backend (`poetry-core`). Refer to (#python-" +"package-build-tools) for more information about frontend and backend " +"compatibility." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:29 +msgid "" +"In this packaging guide we recommend using `hatch` along with its " +"preferred backend `hatchling`. While this will be suitable for most " +"packages, an alternate backend may be used with Hatch if needed when " +"creating an extension module. A Python extension module is one that is " +"made up, either in part or entirely, of compiled code. In this case the " +"backend chosen (such as `meson-python`) must know how to compile the " +"extension language and bind it to Python. `hatchling` does not know how " +"to do this all on its own and must either make use of " +"[plugins](https://hatch.pypa.io/1.9/plugins/about/) or be replaced by a " +"backend that is already capable of building extension modules." +msgstr "" + +#: ../../package-structure-code/complex-python-package-builds.md:37 +msgid "" +"In order to use a different backend you will need to edit your project's " +"`pyproject.toml`. If you have a `pyproject.toml` generated by the `hatch`" +" command, or from following the packaging tutorial, you may have to make " +"a change like this" +msgstr "" + +#: ../../package-structure-code/declare-dependencies.md:8 +#: ../../package-structure-code/declare-dependencies.md:375 +#: ../../package-structure-code/pyproject-toml-python-package-metadata.md: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/jp/LC_MESSAGES/tests.po b/locales/jp/LC_MESSAGES/tests.po new file mode 100644 index 00000000..b0efcaa7 --- /dev/null +++ b/locales/jp/LC_MESSAGES/tests.po @@ -0,0 +1,1002 @@ +# 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-08-02 18:04+0900\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: jp\n" +"Language-Team: jp \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" + +#: ../../tests/index.md:72 +msgid "Intro" +msgstr "" + +#: ../../tests/index.md:72 +msgid "Write tests" +msgstr "" + +#: ../../tests/index.md:72 +msgid "Test types" +msgstr "" + +#: ../../tests/index.md:72 +msgid "Run tests locally" +msgstr "" + +#: ../../tests/index.md:72 +msgid "Run tests online (using CI)" +msgstr "" + +#: ../../tests/index.md:72 +msgid "Create & Run Tests" +msgstr "" + +#: ../../tests/index.md:1 +msgid "Tests and data for your Python package" +msgstr "" + +#: ../../tests/index.md:3 +msgid "" +"Tests are an important part of your Python package because they provide a" +" set of checks that ensure that your package is functioning how you " +"expect it to." +msgstr "" + +#: ../../tests/index.md:7 +msgid "" +"In this section you will learn more about the importance of writing tests" +" for your Python package and how you can setup infrastructure to run your" +" tests both locally and on GitHub." +msgstr "" + +#: ../../tests/index.md:19 +msgid "✨ Why write tests ✨" +msgstr "" + +#: ../../tests/index.md:24 +msgid "" +"Learn more about the art of writing tests for your Python package. Learn " +"about why you should write tests and how they can help you and potential " +"contributors to your project." +msgstr "" + +#: ../../tests/index.md:31 +msgid "✨ Types of tests ✨" +msgstr "" + +#: ../../tests/index.md:36 +msgid "" +"There are three general types of tests that you can write for your Python" +" package: unit tests, integration tests and end-to-end (or functional) " +"tests. Learn about all three." +msgstr "" + +#: ../../tests/index.md:42 +msgid "✨ Run tests locally ✨" +msgstr "" + +#: ../../tests/index.md:47 +msgid "" +"If you expect your users to use your package across different versions of" +" Python, then using an automation tool such as nox to run your tests is " +"useful. Learn about the various tools that you can use to run your tests " +"across python versions here." +msgstr "" + +#: ../../tests/index.md:53 +msgid "✨ Run tests online (using CI) ✨" +msgstr "" + +#: ../../tests/index.md:58 +msgid "" +"Continuous integration platforms such as GitHub actions can be useful for" +" running your tests across both different Python versions and different " +"operating systems. Learn about setting up tests to run in Continuous " +"Integration here." +msgstr "" + +#: ../../tests/index.md:69 +msgid "Graphic showing the elements of the packaging process." +msgstr "" + +#: ../../tests/run-tests.md:6 +msgid "Run Python package tests" +msgstr "" + +#: ../../tests/run-tests.md:8 +msgid "" +"Running your tests is important to ensure that your package is working as" +" expected. It's good practice to consider that tests will run on your " +"computer and your users' computers that may be running a different Python" +" version and operating systems. Think about the following when running " +"your tests:" +msgstr "" + +#: ../../tests/run-tests.md:11 +msgid "" +"Run your test suite in a matrix of environments that represent the Python" +" versions and operating systems your users are likely to have." +msgstr "" + +#: ../../tests/run-tests.md:12 +msgid "" +"Running your tests in an isolated environment provides confidence in the " +"tests and their reproducibility. This ensures that tests do not pass " +"randomly due to your computer's specific setup. For instance, you might " +"have unexpectedly installed dependencies on your local system that are " +"not declared in your package's dependency list. This oversight could lead" +" to issues when others try to install or run your package on their " +"computers." +msgstr "" + +#: ../../tests/run-tests.md:14 +msgid "" +"On this page, you will learn about the tools that you can use to both run" +" tests in isolated environments and across Python versions." +msgstr "" + +#: ../../tests/run-tests.md:19 +msgid "Tools to run your tests" +msgstr "" + +#: ../../tests/run-tests.md:21 +msgid "" +"There are three categories of tools that will make is easier to setup and" +" run your tests in various environments:" +msgstr "" + +#: ../../tests/run-tests.md:24 +msgid "" +"A **test framework**, is a package that provides a particular syntax and " +"set of tools for _both writing and running your tests_. Some test " +"frameworks also have plugins that add additional features such as " +"evaluating how much of your code the tests cover. Below you will learn " +"about the **pytest** framework which is one of the most commonly used " +"Python testing frameworks in the scientific ecosystem. Testing frameworks" +" are essential but they only serve to run your tests. These frameworks " +"don't provide a way to easily run tests across Python versions without " +"the aid of additional automation tools." +msgstr "" + +#: ../../tests/run-tests.md:25 +msgid "" +"**Automation tools** allow you to automate running workflows such as " +"tests in specific ways using user-defined commands. For instance it's " +"useful to be able to run tests across different Python versions with a " +"single command. Tools such as " +"[**nox**](https://nox.thea.codes/en/stable/index.html) and " +"[**tox**](https://tox.wiki/en/latest/index.html) also allow you to run " +"tests across Python versions. However, it will be difficult to test your " +"build on different operating systems using only nox and tox - this is " +"where continuous integration (CI) comes into play." +msgstr "" + +#: ../../tests/run-tests.md:26 +msgid "" +"**Continuous Integration (CI):** is the last tool that you'll need to run" +" your tests. CI will not only allow you to replicate any automated builds" +" you create using nox or tox to run your package in different Python " +"environments. It will also allow you to run your tests on different " +"operating systems (Windows, Mac and Linux). [We discuss using CI to run " +"tests here](tests-ci)." +msgstr "" + +#: ../../tests/run-tests.md:28 +msgid "Table: Testing & Automation Tool" +msgstr "" + +#: ../../tests/run-tests.md:35 +msgid "Features" +msgstr "" + +#: ../../tests/run-tests.md:36 +msgid "Testing Framework (pytest)" +msgstr "" + +#: ../../tests/run-tests.md:37 +msgid "Test Runner (Tox)" +msgstr "" + +#: ../../tests/run-tests.md:38 +msgid "Automation Tools (Nox)" +msgstr "" + +#: ../../tests/run-tests.md:39 +msgid "Continuous Integration (GitHub Actions)" +msgstr "" + +#: ../../tests/run-tests.md:40 +msgid "Run Tests Locally" +msgstr "" + +#: ../../tests/run-tests.md:41 ../../tests/run-tests.md:42 +#: ../../tests/run-tests.md:43 ../../tests/run-tests.md:49 +#: ../../tests/run-tests.md:52 ../../tests/run-tests.md:53 +#: ../../tests/run-tests.md:54 ../../tests/run-tests.md:57 +#: ../../tests/run-tests.md:58 ../../tests/run-tests.md:59 +#: ../../tests/run-tests.md:64 ../../tests/run-tests.md:68 +#: ../../tests/run-tests.md:69 +msgid "" +msgstr "" + +#: ../../tests/run-tests.md:44 ../../tests/run-tests.md:46 +#: ../../tests/run-tests.md:47 ../../tests/run-tests.md:48 +#: ../../tests/run-tests.md:51 ../../tests/run-tests.md:56 +#: ../../tests/run-tests.md:61 ../../tests/run-tests.md:62 +#: ../../tests/run-tests.md:63 ../../tests/run-tests.md:66 +#: ../../tests/run-tests.md:67 +msgid "" +msgstr "" + +#: ../../tests/run-tests.md:45 +msgid "Run Tests Online" +msgstr "" + +#: ../../tests/run-tests.md:50 +msgid "Run Tests Across Python Versions" +msgstr "" + +#: ../../tests/run-tests.md:55 +msgid "Run Tests In Isolated Environments" +msgstr "" + +#: ../../tests/run-tests.md:60 +msgid "Run Tests Across Operating Systems (Windows, MacOS, Linux)" +msgstr "" + +#: ../../tests/run-tests.md:65 +msgid "Use for other automation tasks (e.g. building docs)" +msgstr "" + +#: ../../tests/run-tests.md:73 +msgid "What testing framework / package should I use to run tests?" +msgstr "" + +#: ../../tests/run-tests.md:75 +msgid "" +"We recommend using `Pytest` to build and run your package tests. Pytest " +"is the most common testing tool used in the Python ecosystem." +msgstr "" + +#: ../../tests/run-tests.md:77 +msgid "" +"[The Pytest package](https://docs.pytest.org/en/latest/) also has a " +"number of extensions that can be used to add functionality such as:" +msgstr "" + +#: ../../tests/run-tests.md:80 +msgid "" +"[pytest-cov](https://pytest-cov.readthedocs.io/en/latest/) allows you to " +"analyze the code coverage of your package during your tests, and " +"generates a report that you can [upload to codecov](https://codecov.io/)." +msgstr "" + +#: ../../tests/run-tests.md:82 ../../tests/run-tests.md:174 +#: ../../tests/test-types.md:14 ../../tests/tests-ci.md:7 +msgid "Todo" +msgstr "" + +#: ../../tests/run-tests.md:83 +msgid "Learn more about code coverage here. (add link)" +msgstr "" + +#: ../../tests/run-tests.md:87 +msgid "" +"Your editor or IDE may add additional convenience for running tests, " +"setting breakpoints, and toggling the `–no-cov` flag. Check your editor's" +" documentation for more information." +msgstr "" + +#: ../../tests/run-tests.md:90 +msgid "Run tests using pytest" +msgstr "" + +#: ../../tests/run-tests.md:92 +msgid "If you are using **pytest**, you can run your tests locally by calling:" +msgstr "" + +#: ../../tests/run-tests.md:95 +msgid "`pytest`" +msgstr "" + +#: ../../tests/run-tests.md:97 +msgid "" +"Or if you want to run a specific test file - let's call this file " +"\"`test_module.py`\" - you can run:" +msgstr "" + +#: ../../tests/run-tests.md:99 +msgid "`pytest test_module.py`" +msgstr "" + +#: ../../tests/run-tests.md:101 +msgid "" +"Learn more from the [get started docs](https://docs.pytest.org/en/7.1.x" +"/getting-started.html)." +msgstr "" + +#: ../../tests/run-tests.md:103 +msgid "" +"Running pytest on your computer is going to run your tests in whatever " +"Python environment you currently have activated. This means that tests " +"will be run on a single version of Python and only on the operating " +"system that you are running locally." +msgstr "" + +#: ../../tests/run-tests.md:108 +msgid "" +"An automation tool can simplify the process of running tests in various " +"Python environments." +msgstr "" + +#: ../../tests/run-tests.md:111 +msgid "Tests across operating systems" +msgstr "" + +#: ../../tests/run-tests.md:112 +msgid "" +"If you want to run your tests across different operating systems you can " +"[continuous integration. Learn more here](tests-ci)." +msgstr "" + +#: ../../tests/run-tests.md:115 +msgid "Tools to automate running your tests" +msgstr "" + +#: ../../tests/run-tests.md:117 +msgid "" +"To run tests on various Python versions or in various specific " +"environments with a single command, you can use an automation tool such " +"as `nox` or `tox`. Both `nox` and `tox` can create an isolated virtual " +"environments. This allows you to easily run your tests in multiple " +"environments and across Python versions." +msgstr "" + +#: ../../tests/run-tests.md:120 +msgid "" +"We will focus on [Nox](https://nox.thea.codes/) in this guide. `nox` is a" +" Python-based automation tool that builds upon the features of both " +"`make` and `tox`. `nox` is designed to simplify and streamline testing " +"and development workflows. Everything that you do with `nox` can be " +"implemented using a Python-based interface." +msgstr "" + +#: ../../tests/run-tests.md:122 +msgid "Other automation tools you'll see in the wild" +msgstr "" + +#: ../../tests/run-tests.md:125 +msgid "" +"**[Tox](https://tox.wiki/en/latest/index.html#useful-links)** is an " +"automation tool that supports common steps such as building " +"documentation, running tests across various versions of Python, and more." +" You can find [a nice overview of tox in the plasmaPy " +"documentation](https://docs.plasmapy.org/en/stable/contributing/testing_guide.html" +"#using-tox)." +msgstr "" + +#: ../../tests/run-tests.md:127 +msgid "" +"**[Hatch](https://github.com/ofek/hatch)** is a modern end-to-end " +"packaging tool that works with the popular build backend called " +"hatchling. `hatch` offers a `tox`-like setup where you can run tests " +"locally using different Python versions. If you are using `hatch` to " +"support your packaging workflow, you may want to also use its testing " +"capabilities rather than using `nox`." +msgstr "" + +#: ../../tests/run-tests.md:129 +msgid "" +"[**make:**](https://www.gnu.org/software/make/manual/make.html) Some " +"developers use Make, which is a build automation tool, for running tests " +"due to its versatility; it's not tied to a specific language and can be " +"used to run various build processes. However, Make's unique syntax and " +"approach can make it more challenging to learn, particularly if you're " +"not already familiar with it. Make also won't manage environments for you" +" like **nox** will do." +msgstr "" + +#: ../../tests/run-tests.md:136 +msgid "Run tests across Python versions with nox" +msgstr "" + +#: ../../tests/run-tests.md:138 +msgid "**Nox** is a great automation tool to learn because it:" +msgstr "" + +#: ../../tests/run-tests.md:140 +msgid "Is Python-based making it accessible if you already know Python and" +msgstr "" + +#: ../../tests/run-tests.md:141 +msgid "Will create isolated environments to run workflows." +msgstr "" + +#: ../../tests/run-tests.md:143 +msgid "" +"`nox` simplifies creating and managing testing environments. With `nox`, " +"you can set up virtual environments, and run tests across Python versions" +" using the environment manager of your choice with a single command." +msgstr "" + +#: ../../tests/run-tests.md:148 +msgid "Nox Installations" +msgstr "" + +#: ../../tests/run-tests.md:150 +msgid "" +"When you install and use nox to run tests across different Python " +"versions, nox will create and manage individual `venv` environments for " +"each Python version that you specify in the nox function." +msgstr "" + +#: ../../tests/run-tests.md:152 +msgid "Nox will manage each environment on its own." +msgstr "" + +#: ../../tests/run-tests.md:154 +msgid "" +"Nox can also be used for other development tasks such as building " +"documentation, creating your package distribution, and testing " +"installations across both PyPI related environments (e.g. venv, " +"virtualenv) and `conda` (e.g. `conda-forge`)." +msgstr "" + +#: ../../tests/run-tests.md:158 +msgid "" +"To get started with nox, you create a `noxfile.py` file at the root of " +"your project directory. You then define commands using Python functions. " +"Some examples of that are below." +msgstr "" + +#: ../../tests/run-tests.md:162 +msgid "Test Environments" +msgstr "" + +#: ../../tests/run-tests.md:164 +msgid "" +"By default, `nox` uses the Python built in `venv` environment manager. A " +"virtual environment (`venv`) is a self-contained Python environment that " +"allows you to isolate and manage dependencies for different Python " +"projects. It helps ensure that project-specific libraries and packages do" +" not interfere with each other, promoting a clean and organized " +"development environment." +msgstr "" + +#: ../../tests/run-tests.md:166 +msgid "" +"An example of using nox to run tests in `venv` environments for Python " +"versions 3.9, 3.10, 3.11 and 3.12 is below." +msgstr "" + +#: ../../tests/run-tests.md:169 +msgid "" +"Note that for the code below to work, you need to have all 4 versions of " +"Python installed on your computer for `nox` to find." +msgstr "" + +#: ../../tests/run-tests.md:172 +msgid "Nox with venv environments" +msgstr "" + +#: ../../tests/run-tests.md:175 +msgid "" +"TODO: add some tests above and show what the output would look like in " +"the examples below..." +msgstr "" + +#: ../../tests/run-tests.md:178 +msgid "" +"Below is an example of setting up nox to run tests using `venv` which is " +"the built in environment manager that comes with base Python." +msgstr "" + +#: ../../tests/run-tests.md:180 +msgid "" +"Note that the example below assumes that you have [setup your " +"`pyproject.toml` to declare test dependencies in a way that pip can " +"understand](../package-structure-code/declare-dependencies.md). An " +"example of that setup is below." +msgstr "" + +#: ../../tests/run-tests.md:201 +msgid "" +"If you have the above setup, then you can use " +"`session.install(\".[tests]\")` to install your test dependencies. Notice" +" that below one single nox session allows you to run your tests on 4 " +"different Python environments (Python 3.9, 3.10, 3.11, and 3.12)." +msgstr "" + +#: ../../tests/run-tests.md:222 +msgid "" +"Above you create a nox session in the form of a function with a " +"`@nox.session` decorator. Notice that within the decorator you declare " +"the versions of python that you wish to run." +msgstr "" + +#: ../../tests/run-tests.md:226 +msgid "" +"To run the above you'd execute the following command, specifying which " +"session with `--session` (sometimes shortened to `-s`). Your function " +"above is called test, therefore the session name is test." +msgstr "" + +#: ../../tests/run-tests.md:234 +msgid "Nox with conda / mamba" +msgstr "" + +#: ../../tests/run-tests.md:236 +msgid "" +"Below is an example for setting up nox to use mamba (or conda) for your " +"environment manager. Note that unlike venv, conda can automatically " +"install the various versions of Python that you need. You won't need to " +"install all four Python versions if you use conda/mamba, like you do with" +" `venv`." +msgstr "" + +#: ../../tests/run-tests.md:242 +msgid "" +"For `conda` to work with `nox`, you will need to ensure that either " +"`conda` or `mamba` is installed on your computer." +msgstr "" + +#: ../../tests/run-tests.md:264 +msgid "To run the above session you'd use:" +msgstr "" + +#: ../../tests/test-types.md:1 +msgid "Test Types for Python packages" +msgstr "" + +#: ../../tests/test-types.md:3 +msgid "Three types of tests: Unit, Integration & Functional Tests" +msgstr "" + +#: ../../tests/test-types.md:5 +msgid "" +"There are different types of tests that you want to consider when " +"creating your test suite:" +msgstr "" + +#: ../../tests/test-types.md:8 +msgid "Unit tests" +msgstr "" + +#: ../../tests/test-types.md:9 +msgid "Integration" +msgstr "" + +#: ../../tests/test-types.md:10 +msgid "End-to-end (also known as Functional) tests" +msgstr "" + +#: ../../tests/test-types.md:12 +msgid "" +"Each type of test has a different purpose. Here, you will learn about all" +" three types of tests." +msgstr "" + +#: ../../tests/test-types.md:15 +msgid "" +"I think this page would be stronger if we did have some examples from our" +" package here: https://github.com/pyOpenSci/pyosPackage" +msgstr "" + +#: ../../tests/test-types.md:20 +msgid "Unit Tests" +msgstr "" + +#: ../../tests/test-types.md:22 +msgid "" +"A unit test involves testing individual components or units of code in " +"isolation to ensure that they work correctly. The goal of unit testing is" +" to verify that each part of the software, typically at the function or " +"method level, performs its intended task correctly." +msgstr "" + +#: ../../tests/test-types.md:24 +msgid "" +"Unit tests can be compared to examining each piece of your puzzle to " +"ensure parts of it are not broken. If all of the pieces of your puzzle " +"don’t fit together, you will never complete it. Similarly, when working " +"with code, tests ensure that each function, attribute, class, method " +"works properly when isolated." +msgstr "" + +#: ../../tests/test-types.md:26 +msgid "" +"**Unit test example:** Pretend that you have a function that converts a " +"temperature value from Celsius to Fahrenheit. A test for that function " +"might ensure that when provided with a value in Celsius, the function " +"returns the correct value in degrees Fahrenheit. That function is a unit " +"test. It checks a single unit (function) in your code." +msgstr "" + +#: ../../tests/test-types.md:44 +msgid "" +"Example unit test for the above function. You'd run this test using the " +"`pytest` command in your **tests/** directory." +msgstr "" + +#: ../../tests/test-types.md:65 ../../tests/test-types.md:115 +msgid "" +"image of puzzle pieces that all fit together nicely. The puzzle pieces " +"are colorful - purple, green and teal." +msgstr "" + +#: ../../tests/test-types.md:69 +msgid "" +"Your unit tests should ensure each part of your code works as expected on" +" its own." +msgstr "" + +#: ../../tests/test-types.md:72 +msgid "Integration tests" +msgstr "" + +#: ../../tests/test-types.md:74 +msgid "" +"Integration tests involve testing how parts of your package work together" +" or integrate. Integration tests can be compared to connecting a bunch of" +" puzzle pieces together to form a whole picture. Integration tests focus " +"on how different pieces of your code fit and work together." +msgstr "" + +#: ../../tests/test-types.md:76 +msgid "" +"For example, if you had a series of steps that collected temperature data" +" in a spreadsheet, converted it from degrees celsius to Fahrenheit and " +"then provided an average temperature for a particular time period. An " +"integration test would ensure that all parts of that workflow behaved as " +"expected." +msgstr "" + +#: ../../tests/test-types.md:107 +msgid "" +"image of two puzzle pieces with some missing parts. The puzzle pieces are" +" purple teal yellow and blue. The shapes of each piece don’t fit " +"together." +msgstr "" + +#: ../../tests/test-types.md:112 +msgid "" +"If puzzle pieces have missing ends, they can’t work together with other " +"elements in the puzzle. The same is true with individual functions, " +"methods and classes in your software. The code needs to work both " +"individually and together to perform certain sets of tasks." +msgstr "" + +#: ../../tests/test-types.md:120 +msgid "" +"Your integration tests should ensure that parts of your code that are " +"expected to work together, do so as expected." +msgstr "" + +#: ../../tests/test-types.md:124 +msgid "End-to-end (functional) tests" +msgstr "" + +#: ../../tests/test-types.md:126 +msgid "" +"End-to-end tests (also referred to as functional tests) in Python are " +"like comprehensive checklists for your software. They simulate real user " +"end-to-end workflows to make sure the code base supports real life " +"applications and use-cases from start to finish. These tests help catch " +"issues that might not show up in smaller tests and ensure your entire " +"application or program behaves correctly. Think of them as a way to give " +"your software a final check before it's put into action, making sure it's" +" ready to deliver a smooth experience to its users." +msgstr "" + +#: ../../tests/test-types.md:128 +msgid "Image of a completed puzzle showing a daisy" +msgstr "" + +#: ../../tests/test-types.md:133 +msgid "" +"End-to-end or functional tests represent an entire workflow that you " +"expect your package to support." +msgstr "" + +#: ../../tests/test-types.md:137 +msgid "" +"End-to-end test also test how a program runs from start to finish. A " +"tutorial that you add to your documentation that runs in CI in an " +"isolated environment is another example of an end-to-end test." +msgstr "" + +#: ../../tests/test-types.md:140 +msgid "" +"For scientific packages, creating short tutorials that highlight core " +"workflows that your package supports, that are run when your " +"documentation is built could also serve as end-to-end tests." +msgstr "" + +#: ../../tests/test-types.md:143 +msgid "Comparing unit, integration and end-to-end tests" +msgstr "" + +#: ../../tests/test-types.md:145 +msgid "" +"Unit tests, integration tests, and end-to-end tests have complementary " +"advantages and disadvantages. The fine-grained nature of unit tests make " +"them well-suited for isolating where errors are occurring. However, unit " +"tests are not useful for verifying that different sections of code work " +"together." +msgstr "" + +#: ../../tests/test-types.md:147 +msgid "" +"Integration and end-to-end tests verify that the different portions of " +"the program work together, but are less well-suited for isolating where " +"errors are occurring. For example, when you refactor your code, it is " +"possible that that your end-to-end tests will break. But if the refactor " +"didn't introduce new behavior to your existing code, then you can rely on" +" your unit tests to continue to pass, testing the original functionality " +"of your code." +msgstr "" + +#: ../../tests/test-types.md:152 +msgid "" +"It is important to note that you don't need to spend energy worrying " +"about the specifics surrounding the different types of tests. When you " +"begin to work on your test suite, consider what your package does and how" +" you may need to test parts of your package. Bring familiar with the " +"different types of tests can provides a framework to help you think about" +" writing tests and how different types of tests can complement each " +"other." +msgstr "" + +#: ../../tests/tests-ci.md:1 +msgid "Run tests with Continuous Integration" +msgstr "" + +#: ../../tests/tests-ci.md:3 +msgid "" +"Running your [test suite locally](run-tests) is useful as you develop " +"code and also test new features or changes to the code base. However, you" +" also will want to setup Continuous Integration (CI) to run your tests " +"online. CI allows you to run all of your tests in the cloud. While you " +"may only be able to run tests locally on a specific operating system, " +"using CI you can specify tests to run both on various versions of Python " +"and across different operating systems." +msgstr "" + +#: ../../tests/tests-ci.md:5 +msgid "" +"CI can also be triggered for pull requests and pushes to your repository." +" This means that every pull request that you, your maintainer team or a " +"contributor submit, can be tested. In the end CI testing ensures your " +"code continues to run as expected even as changes are made to the code " +"base." +msgstr "" + +#: ../../tests/tests-ci.md:9 +msgid "" +"Learn more about Continuous Integration and how it can be used, here. " +"(add link)" +msgstr "" + +#: ../../tests/tests-ci.md:13 +msgid "CI & pull requests" +msgstr "" + +#: ../../tests/tests-ci.md:15 +msgid "" +"CI is invaluable if you have outside people contributing to your " +"software. You can setup CI to run on all pull requests submitted to your " +"repository. CI can make your repository more friendly to new potential " +"contributors. It allows users to contribute code, documentation fixes and" +" more without having to create development environments, run tests and " +"build documentation locally." +msgstr "" + +#: ../../tests/tests-ci.md:22 +msgid "Example GitHub action that runs tests" +msgstr "" + +#: ../../tests/tests-ci.md:24 +msgid "" +"Below is an example GitHub action that runs tests using nox across both " +"Windows, Mac and Linux and on Python versions 3.9-3.11." +msgstr "" + +#: ../../tests/tests-ci.md:28 +msgid "" +"To work properly, this file should be located in a root directory of your" +" GitHub repository:" +msgstr "" + +#: ../../tests/write-tests.md:1 +msgid "Write tests for your Python package" +msgstr "" + +#: ../../tests/write-tests.md:3 +msgid "" +"Writing code that tests your package code, also known as test suites, is " +"important for you as a maintainer, your users, and package contributors. " +"Test suites consist of sets of functions, methods, and classes that are " +"written with the intention of making sure a specific part of your code " +"works as you expected it to." +msgstr "" + +#: ../../tests/write-tests.md:7 +msgid "Why write tests for your package?" +msgstr "" + +#: ../../tests/write-tests.md:9 +msgid "" +"Tests act as a safety net for code changes. They help you spot and " +"rectify bugs before they affect users. Tests also instill confidence that" +" code alterations from contributors won't breaking existing " +"functionality." +msgstr "" + +#: ../../tests/write-tests.md:13 +msgid "Writing tests for your Python package is important because:" +msgstr "" + +#: ../../tests/write-tests.md:15 +msgid "" +"**Catch Mistakes:** Tests are a safety net. When you make changes or add " +"new features to your package, tests can quickly tell you if you " +"accidentally broke something that was working fine before." +msgstr "" + +#: ../../tests/write-tests.md:16 +msgid "" +"**Save Time:** Imagine you have a magic button that can automatically " +"check if your package is still working properly. Tests are like that " +"magic button! They can run all those checks for you saving you time." +msgstr "" + +#: ../../tests/write-tests.md:17 +msgid "" +"**Easier Collaboration:** If you're working with others, or have outside " +"contributors, tests help everyone stay on the same page. Your tests " +"explain how your package is supposed to work, making it easier for others" +" to understand and contribute to your project." +msgstr "" + +#: ../../tests/write-tests.md:18 +msgid "" +"**Fearless Refactoring:** Refactoring means making improvements to your " +"code structure without changing its behavior. Tests empower you to make " +"these changes as if you break something, test failures will let you know." +msgstr "" + +#: ../../tests/write-tests.md:19 +msgid "" +"**Documentation:** Tests serve as technical examples of how to use your " +"package. This can be helpful for a new technical contributor that wants " +"to contribute code to your package. They can look at your tests to " +"understand how parts of your code functionality fits together." +msgstr "" + +#: ../../tests/write-tests.md:20 +msgid "" +"**Long-Term ease of maintenance:** As your package evolves, tests ensure " +"that your code continues to behave as expected, even as you make changes " +"over time. Thus you are helping your future self when writing tests." +msgstr "" + +#: ../../tests/write-tests.md:21 +msgid "" +"**Easier pull request reviews:** By running your tests in a CI framework " +"such as GitHub actions, each time you or a contributor makes a change to " +"your code-base, you can catch issues and things that may have changed in " +"your code base. This ensures that your software behaves the way you " +"expect it to." +msgstr "" + +#: ../../tests/write-tests.md:23 +msgid "Tests for user edge cases" +msgstr "" + +#: ../../tests/write-tests.md:25 +msgid "" +"Edge cases refer to unexpected or \"outlier\" ways that some users may " +"use your package. Tests enable you to address various edge cases that " +"could impair your package's functionality. For example, what occurs if a " +"function expects a pandas `dataframe` but a user supplies a numpy " +"`array`? Does your code gracefully handle this situation, providing clear" +" feedback, or does it leave users frustrated by an unexplained failure?" +msgstr "" + +#: ../../tests/write-tests.md:33 +msgid "" +"For a good introduction to testing, see [this Software Carpentry " +"lesson](https://swcarpentry.github.io/python-novice-" +"inflammation/10-defensive.html)" +msgstr "" + +#: ../../tests/write-tests.md:41 +msgid "" +"Imagine you're working on a puzzle where each puzzle piece represents a " +"function, method, class or attribute in your Python package that you want" +" other people to be able to use. Would you want to give someone a puzzle " +"that has missing pieces or pieces that don't fit together? Providing " +"people with the right puzzle pieces that work together can be compared to" +" writing tests for your Python package." +msgstr "" + +#: ../../tests/write-tests.md:44 +msgid "Test examples" +msgstr "" + +#: ../../tests/write-tests.md:47 +msgid "" +"Let’s say you have a Python function that adds two numbers a and b " +"together." +msgstr "" + +#: ../../tests/write-tests.md:54 +msgid "" +"A test to ensure that function runs as you might expect when provided " +"with different numbers might look like this:" +msgstr "" + +#: ../../tests/write-tests.md:72 +msgid "🧩🐍" +msgstr "" + +#: ../../tests/write-tests.md:74 +msgid "How do I know what type of tests to write?" +msgstr "" + +#: ../../tests/write-tests.md:77 +msgid "" +"This section has been adapted from [a presentation by Nick " +"Murphy](https://zenodo.org/record/8185113)." +msgstr "" + +#: ../../tests/write-tests.md:80 +msgid "" +"At this point, you may be wondering - what should you be testing in your " +"package? Below are a few examples:" +msgstr "" + +#: ../../tests/write-tests.md:82 +msgid "" +"**Test some typical cases:** Test that the package functions as you " +"expect it to when users use it. For instance, if your package is supposed" +" to add two numbers, test that the outcome value of adding those two " +"numbers is correct." +msgstr "" + +#: ../../tests/write-tests.md:84 +msgid "" +"**Test special cases:** Sometimes there are special or outlier cases. For" +" instance, if a function performs a specific calculation that may become " +"problematic closer to the value = 0, test it with the input of both 0 and" +msgstr "" + +#: ../../tests/write-tests.md:86 +msgid "" +"**Test at and near the expected boundaries:** If a function requires a " +"value that is greater than or equal to 1, make sure that the function " +"still works with both the values 1 and less than one and 1.001 as well " +"(something close to the constraint value).." +msgstr "" + +#: ../../tests/write-tests.md:88 +msgid "" +"**Test that code fails correctly:** If a function requires a value " +"greater than or equal to 1, then test at 0.999. Make sure that the " +"function fails gracefully when given unexpected values and help and that " +"the user can easily understand why if failed (provides a useful error " +"message)." +msgstr "" + diff --git a/locales/jp/LC_MESSAGES/tutorials.po b/locales/jp/LC_MESSAGES/tutorials.po new file mode 100644 index 00000000..2f77b15f --- /dev/null +++ b/locales/jp/LC_MESSAGES/tutorials.po @@ -0,0 +1,5536 @@ +# 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-08-02 18:04+0900\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: jp\n" +"Language-Team: jp \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 +msgid "Get to Know Hatch" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:3 +msgid "" +"Our Python packaging tutorials use the tool " +"[Hatch](https://hatch.pypa.io/latest/). While there are [many great " +"packaging tools](/package-structure-code/python-package-build-tools) out " +"there, we have selected Hatch because:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:8 +msgid "" +"It is an end-to-end tool that supports most of the steps required to " +"create a quality Python package. Beginners will have fewer tools to learn" +" if they use Hatch." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:11 +msgid "" +"It supports different build back-ends if you ever need to compile code in" +" other languages." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:13 +msgid "" +"As a community, pyOpenSci has decided that Hatch is a user-friendly tool " +"that supports many different scientific Python use cases." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:16 +msgid "" +"In this tutorial, you will install and get to know Hatch a bit more " +"before starting to use it." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:19 +msgid "You need two things to successfully complete this tutorial:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:21 +msgid "You need Python installed." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:22 +msgid "You need Hatch installed." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:25 +msgid "" +"If you don't already have Python installed on your computer, Hatch will " +"do it for you when you install Hatch." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:29 +msgid "Install Hatch" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:31 +msgid "" +"To begin, follow the operating-system-specific instructions below to " +"install Hatch." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md +msgid "MAC" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:38 +msgid "" +"Follow the instructions " +"[here](https://hatch.pypa.io/latest/install/#installers)." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:40 +msgid "" +"Download the latest GUI installer for MAC [hatch-" +"universal.pkg](https://github.com/pypa/hatch/releases/latest/download" +"/hatch-universal.pkg)." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:41 +msgid "Run the installer and follow the setup instructions." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:42 +msgid "If your terminal is open, then restart it." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md +msgid "Windows" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:48 +msgid "" +"In your browser, download the correct `.msi` file for your system: " +"[hatch-x64.msi](https://github.com/pypa/hatch/releases/latest/download/hatch-x64.msi)" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:50 +msgid "Run your downloaded installer file and follow the on-screen instructions." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md +msgid "Linux" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:56 +msgid "" +"We suggest that you install Hatch using pipx on Linux. however, if you " +"prefer another method, check out the [Hatch installation " +"documentation](https://hatch.pypa.io/latest/install/) for other methods." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:70 +msgid "" +"Hatch can also be installed directly using " +"[pip](https://hatch.pypa.io/latest/install/#pip) or " +"[conda](https://hatch.pypa.io/latest/install/#conda). We encourage you to" +" follow the instructions above because we have found that the Hatch " +"installers for Windows and Mac are the easiest and most efficient." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:74 +msgid "" +"Our Linux users have found success installing Hatch with pipx if they " +"already use apt install." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:77 +msgid "" +"Both approaches (using a graphical installer on Windows/Mac and pipx) " +"ensure that you have Hatch installed globally. A global install means " +"that Hatch is available across all of your Python environments on your " +"computer." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:82 +msgid "Check that hatch installed correctly" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:84 +msgid "" +"Once you have completed the installation instructions above, you can open" +" your terminal, and make sure that Hatch installed correctly using the " +"command below:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:92 +msgid "" +"*Note the version number output of `hatch --version` will likely be " +"different from the output above in this tutorial.*" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:95 +msgid "Configure Hatch" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:97 +msgid "" +"Once you have installed Hatch, you can customize its configuration. This " +"includes setting the default name and setup for every package you create." +" While this step is not required, we suggest that you do it." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:101 +msgid "" +"Hatch stores your configuration in a [`config.toml` " +"file](https://hatch.pypa.io/latest/config/project-templates/)." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:103 +msgid "" +"While you can update the `config.toml` file through the command line, it " +"might be easier to look at and update it in a text editor if you are " +"using it for the first time." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:107 +msgid "Step 1: Open and Edit Your `config.toml` File" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:109 +msgid "" +"To open the config file in your file browser, run the following command " +"in your shell:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:112 +msgid "`hatch config explore`" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:114 +msgid "" +"This will open up a directory window that allows you to double-click on " +"the file and open it in your favorite text editor." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:117 +msgid "" +"You can also retrieve the location of the Hatch config file by running " +"the following command in your shell:" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:125 +msgid "Step 2 - update your email and name" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:127 +msgid "" +"Once the file is open, update the [template] table of the `config.toml` " +"file with your name and email. This information will be used in any " +"`pyproject.toml` metadata files that you create using Hatch." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:137 +msgid "Step 3" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:139 +msgid "Next, set tests to false in the `[template.plugins.default]` table." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:141 +msgid "" +"While tests are important, setting the tests configuration in Hatch to " +"`true` will create a more complex `pyproject.toml` file. You won't need " +"to use this feature in this beginner friendly tutorial series but we will" +" introduce it in later tutorials." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:146 +msgid "Your `config.toml` file should look something like the one below." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:184 +msgid "" +"Also notice that the default license option is MIT. While we will discuss" +" license in more detail in a later lesson, the MIT license is the " +"recommended permissive license from " +"[choosealicense.com](https://www.choosealicense.com) and as such we will " +"use it for this tutorial series." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:190 +msgid "You are of course welcome to select another license." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:192 +#: ../../tutorials/installable-code.md:22 +#: ../../tutorials/installable-code.md:411 +#: ../../tutorials/installable-code.md:502 ../../tutorials/intro.md: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:193 +msgid "" +"I think we'd need the SPDX license options here if they want to chose " +"bsd-3 for instance" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:196 +msgid "Step 4: Close the config file and run `hatch config show`" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:198 +msgid "" +"Once you have completed the steps above run the following command in your" +" shell." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:200 +msgid "`hatch config show`" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:202 +msgid "" +"`hatch config show` will print out the contents of your `config.toml` " +"file in your shell. look at the values and ensure that your name, email " +"is set. Also make sure that `tests=false`." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:206 +msgid "Hatch features" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:208 +msgid "" +"Hatch offers a suite of features that will make creating, publishing and " +"maintaining your Python package easier." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:211 +msgid "Comparison to other tools" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:213 +msgid "" +"[We compared Hatch to several of the other popular packaging tools in the" +" ecosystem including flit, pdm and poetry. Learn more here](package-" +"features)" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:216 +msgid "[More on Hatch here](hatch)" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:218 +msgid "A few features that Hatch offers" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:220 +msgid "" +"it will convert metadata stored in a `setup.py` or `setup.cfg` file to a " +"pyproject.toml file for you (see [Migrating setup.py to pyproject.toml " +"using Hatch](setup-py-to-pyproject-toml.md ))" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:222 +msgid "" +"It will help you by storing configuration information for publishing to " +"PyPI after you've entered it once." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:224 +msgid "Use `hatch -h` to see all of the available commands." +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:226 +msgid "What's next" +msgstr "" + +#: ../../tutorials/get-to-know-hatch.md:228 +msgid "" +"In the next lesson you'll learn how to package and make your code " +"installable using Hatch." +msgstr "" + +#: ../../tutorials/installable-code.md:6 +msgid "Make your Python code installable" +msgstr "" + +#: ../../tutorials/installable-code.md:8 +msgid "What we previously covered" +msgstr "" + +#: ../../tutorials/installable-code.md:9 +msgid "" +"[In the previous lesson](intro), you learned about what a Python package " +"is. You also learned about the [benefits of creating a Python package" +"](package-benefits)." +msgstr "" + +#: ../../tutorials/installable-code.md:13 +msgid "" +"Your next step in our packaging tutorial series is to create a Python " +"package that is installable both locally and remotely from a website such" +" as GitHub (or GitLab). The package that you create in this lesson will " +"have the bare minimum elements needed to be installable into a Python " +"environment." +msgstr "" + +#: ../../tutorials/installable-code.md:18 +msgid "" +"Making your code installable is an important steps towards creating a " +"full Python package that is directly installable from PyPI." +msgstr "" + +#: ../../tutorials/installable-code.md:23 +msgid "" +"Is it clear where to add commands? Bash vs. Python console Bash vs. Zsh " +"is different" +msgstr "" + +#: ../../tutorials/installable-code.md:25 +msgid "Does this lesson run as expected on windows and mac?" +msgstr "" + +#: ../../tutorials/installable-code.md:26 +msgid "" +"ADD: note about what makes something \"package worthy\", with a common " +"misconception being that a package should be production-ready code that's" +" valuable to a broad audience. this may not be a pervasive misconception " +"in Python, but a quick break-out with an explanation of what a package " +"can consist of would be helpful." +msgstr "" + +#: ../../tutorials/installable-code.md:31 +msgid "" +"Diagram showing the basic steps to creating an installable package. There" +" are 4 boxes with arrows pointing towards the right. The boxes read, your" +" code, create package structure, add metadata to pyproject.toml and pip " +"install package." +msgstr "" + +#: ../../tutorials/installable-code.md:33 +msgid "" +"A basic installable package needs a few things: code, a [specific package" +" file structure](https://www.pyopensci.org/python-package-guide/package-" +"structure-code/python-package-structure.html) and a `pyproject.toml` " +"containing your package's name and version. Once you have these items in " +"the correct directory structure, you can pip install your package into " +"any environment on your computer. You will learn how to create a basic " +"installable package in this lesson." +msgstr "" + +#: ../../tutorials/installable-code.md:37 +msgid "About this lesson" +msgstr "" + +#: ../../tutorials/installable-code.md:43 +msgid "" +"How to make your code installable into any Python environment both " +"locally and from GitHub" +msgstr "" + +#: ../../tutorials/installable-code.md:44 +msgid "" +"How to create a basic `pyproject.toml` file that includes package " +"dependencies and metadata. This file is required to make your package " +"installable." +msgstr "" + +#: ../../tutorials/installable-code.md:45 +msgid "" +"How to declare a [build backend](build_backends) which will be used to " +"[build](build-package) and install your package" +msgstr "" + +#: ../../tutorials/installable-code.md:46 +msgid "How to install your package in editable mode for interactive development" +msgstr "" + +#: ../../tutorials/installable-code.md:48 +msgid "**What you need to complete this lesson**" +msgstr "" + +#: ../../tutorials/installable-code.md:50 +msgid "" +"To complete this lesson you will need a local Python environment and " +"shell on your computer. You will also need to have [Hatch installed](get-" +"to-know-hatch)." +msgstr "" + +#: ../../tutorials/installable-code.md:53 +msgid "" +"If you are using Windows or are not familiar with Shell, you may want to " +"check out the Carpentries shell lesson[^shell-lesson]. Windows users will" +" likely need to configure a tool for any Shell and git related steps." +msgstr "" + +#: ../../tutorials/installable-code.md:55 +msgid "**What comes next**" +msgstr "" + +#: ../../tutorials/installable-code.md:57 +msgid "In the upcoming lessons you will learn how to:" +msgstr "" + +#: ../../tutorials/installable-code.md:59 +msgid "[Publish your package to PyPI](publish-pypi)" +msgstr "" + +#: ../../tutorials/installable-code.md:60 +msgid "Add a README file to your package to support community use" +msgstr "" + +#: ../../tutorials/installable-code.md:61 +msgid "" +"Add additional project metadata to your package to support PyPI " +"publication" +msgstr "" + +#: ../../tutorials/installable-code.md:67 +msgid "" +"This diagram has two smaller boxes with arrows pointing to the right to a" +" Python environment. The small boxes read your-package and pip install " +"package. The environment box on the right reads - your Python " +"environment. It them lists your-package along with a few other core " +"packages such as Matplotlib, NumPy, Pandas, Xarray and GeoPandas." +msgstr "" + +#: ../../tutorials/installable-code.md:69 +msgid "" +"Making your code installable is the first step towards creating a " +"publishable Python package. Once your code is installable, it is a Python" +" package and can be added to any Python environment on your computer and " +"imported in the same way that you might import a package such as Pandas " +"or GeoPandas. If your code is on GitHub or GitLab you can also install it" +" directly from there." +msgstr "" + +#: ../../tutorials/installable-code.md:74 +msgid "About the Python package directory structure" +msgstr "" + +#: ../../tutorials/installable-code.md:76 +msgid "" +"To make your Python code installable you need to create a specific " +"directory structure with the following elements:" +msgstr "" + +#: ../../tutorials/installable-code.md:78 +msgid "A `pyproject.toml` file." +msgstr "" + +#: ../../tutorials/installable-code.md:79 +msgid "A specific directory structure." +msgstr "" + +#: ../../tutorials/installable-code.md:80 +msgid "Some code." +msgstr "" + +#: ../../tutorials/installable-code.md:81 +msgid "An `__init__.py` file in your code directory." +msgstr "" + +#: ../../tutorials/installable-code.md:83 +msgid "The directory structure you’ll create in this lesson will look like this:" +msgstr "" + +#: ../../tutorials/installable-code.md:95 +msgid "About the basic package directory structure" +msgstr "" + +#: ../../tutorials/installable-code.md:97 +msgid "Notice a few things about the above layout:" +msgstr "" + +#: ../../tutorials/installable-code.md:99 +msgid "" +"Your package code lives within a `src/packagename` directory. We suggest " +"that you use `src` (short for **source code**) directory as it [ensures " +"that you are running tests on the installed version of your " +"code](https://www.pyopensci.org/python-package-guide/package-structure-" +"code/python-package-structure.html#the-src-layout-and-testing)." +msgstr "" + +#: ../../tutorials/installable-code.md:100 +msgid "" +"Within the `src` directory you have a package directory called " +"`pyospackage`. Use the name of your package for that directory name. This" +" will be the name for importing your package in Python code once " +"installed." +msgstr "" + +#: ../../tutorials/installable-code.md:101 +msgid "" +"In your package directory, you have an `__init__.py` file and all of your" +" Python modules. You will learn more about the `__init__.py` file below." +msgstr "" + +#: ../../tutorials/installable-code.md:102 +msgid "The `pyproject.toml` file lives at the root directory of your package." +msgstr "" + +#: ../../tutorials/installable-code.md:103 +msgid "" +"The name of the root directory for the package is **pyospackage** which " +"is the name of the package. This is not a requirement but you will often " +"see that the GitHub / GitLab repository and the root directory name are " +"the same as the package name." +msgstr "" + +#: ../../tutorials/installable-code.md:105 +msgid "What is an `__init__.py` file?" +msgstr "" + +#: ../../tutorials/installable-code.md:107 +msgid "" +"The `__init__.py` file tells Python that a directory should be treated as" +" a Python package. As such, a directory with an `__init__.py` file can be" +" imported directly into Python. The `__init__.py` file does not need to " +"contain any code in order for Python to recognize it; it can be empty." +msgstr "" + +#: ../../tutorials/installable-code.md:111 +msgid "" +"For example, following the file structure example above which has an " +"`__init__.py` file within it, you can run:" +msgstr "" + +#: ../../tutorials/installable-code.md:117 ../../tutorials/pyproject-toml.md:48 +msgid "What is a pyproject.toml file?" +msgstr "" + +#: ../../tutorials/installable-code.md:119 +msgid "The **pyproject.toml** file is:" +msgstr "" + +#: ../../tutorials/installable-code.md:121 +msgid "" +"Where you define your project’s metadata (including its name, authors, " +"license, etc)" +msgstr "" + +#: ../../tutorials/installable-code.md:122 +msgid "Where you define dependencies (the packages that it depends on)" +msgstr "" + +#: ../../tutorials/installable-code.md:123 +msgid "" +"Used to specify and configure what build backend you want to use to " +"[build your package](../package-structure-code/python-package-" +"distribution-files-sdist-wheel)." +msgstr "" + +#: ../../tutorials/installable-code.md:125 +msgid "" +"After the `__init__.py` and `pyproject.toml` files have been added, your " +"package can be built and distributed as an installable Python package " +"using tools such as pip. Note that the `pyproject.toml` file needs to " +"have a few basic items defined for the package to be installable " +"including:" +msgstr "" + +#: ../../tutorials/installable-code.md:131 +msgid "The `build-backend` that you want to use," +msgstr "" + +#: ../../tutorials/installable-code.md:132 +msgid "The project `name` and `version`." +msgstr "" + +#: ../../tutorials/installable-code.md:134 +msgid "Why the pyproject.toml file is important" +msgstr "" + +#: ../../tutorials/installable-code.md:138 +msgid "" +"The `pyproject.toml` file replaces some of the functionality of both the " +"`setup.py` file and `setup.cfg` files. If you try to pip install a " +"package with no `pyproject.toml` you will get the following error:" +msgstr "" + +#: ../../tutorials/installable-code.md:150 +msgid "Note about `setup.py`" +msgstr "" + +#: ../../tutorials/installable-code.md:154 +msgid "" +"If your project already defines a `setup.py` file, Hatch can be used to " +"automatically create the `pyproject.toml`." +msgstr "" + +#: ../../tutorials/installable-code.md:155 +msgid "" +"See [Using Hatch to Migrate setup.py to a pyproject.toml ](setup-py-to-" +"pyproject-toml.md)" +msgstr "" + +#: ../../tutorials/installable-code.md:161 +msgid "Time to create your Python package!" +msgstr "" + +#: ../../tutorials/installable-code.md:163 +msgid "" +"Now that you understand the basics of the Python package directory " +"structure, and associated key files (`__init__.py` and `pyproject.toml`)," +" it's time to create your Python package! Below you will create a " +"directory structure similar to the structure described above using Hatch." +msgstr "" + +#: ../../tutorials/installable-code.md:167 +msgid "Step 1: Set Up the Package Directory Structure" +msgstr "" + +#: ../../tutorials/installable-code.md:169 +msgid "Open your shell or preferred terminal." +msgstr "" + +#: ../../tutorials/installable-code.md:170 +msgid "" +"Use the shell `cd` command to navigate in your shell to the location " +"where you'd like your package directory to live. Hatch will create the " +"package directory for you" +msgstr "" + +#: ../../tutorials/installable-code.md:171 +msgid "Choose a name for your package. The name should:" +msgstr "" + +#: ../../tutorials/installable-code.md:172 +msgid "Have no spaces (*Required*)" +msgstr "" + +#: ../../tutorials/installable-code.md:173 +msgid "" +"Use all lowercase characters (*Recommended*). For this tutorial we will " +"use `pyospackage`." +msgstr "" + +#: ../../tutorials/installable-code.md:174 +msgid "" +"Only use letter and the characters _ or - in the name. This means that " +"the name `pyos*package` is not an acceptable name. However, the names " +"`pyos_package` or `pyos-package` both are ok" +msgstr "" + +#: ../../tutorials/installable-code.md:176 +msgid "Hatch and project names" +msgstr "" + +#: ../../tutorials/installable-code.md:177 +msgid "" +"Hatch makes some decisions for your project's name when you run `hatch " +"new`" +msgstr "" + +#: ../../tutorials/installable-code.md:179 +msgid "These include using:" +msgstr "" + +#: ../../tutorials/installable-code.md:180 +msgid "dashes for the top level directory" +msgstr "" + +#: ../../tutorials/installable-code.md:181 +msgid "dashes for the project name in the pyproject.toml" +msgstr "" + +#: ../../tutorials/installable-code.md:182 +msgid "underscores for the package directory name" +msgstr "" + +#: ../../tutorials/installable-code.md:196 +msgid "If you use a name with underscores, Hatch will return the same thing:" +msgstr "" + +#: ../../tutorials/installable-code.md:209 +msgid "" +"In both of the examples above the project name in the pyproject.toml file" +" that hatch creates is `pyos-package`." +msgstr "" + +#: ../../tutorials/installable-code.md:213 +msgid "Next run:" +msgstr "" + +#: ../../tutorials/installable-code.md:228 +msgid "Your final project directory structure should look like this:" +msgstr "" + +#: ../../tutorials/installable-code.md:243 +msgid "Step 2: Add module to your package" +msgstr "" + +#: ../../tutorials/installable-code.md:245 +msgid "" +"A Python module refers to a `.py` file containing the code that you want " +"your package to access and run. Within the `pyospackage` subdirectory, " +"add at least one Python modules (.py files)." +msgstr "" + +#: ../../tutorials/installable-code.md:247 +msgid "" +"If you don't have code already and are just learning how to create a " +"Python package, then create an empty `add_numbers.py` file. You will " +"populate the `add_numbers.py` file with code provided below." +msgstr "" + +#: ../../tutorials/installable-code.md:250 +msgid "Python modules and the `__init__.py` file" +msgstr "" + +#: ../../tutorials/installable-code.md:254 +msgid "" +"When you see the word module, we are referring to a `.py` file containing" +" Python code." +msgstr "" + +#: ../../tutorials/installable-code.md:257 +msgid "" +"The `__init__.py` allows Python to recognize that a directory contains " +"at least one module that may be imported and used in your code. A package" +" can have multiple modules[^python-modules]." +msgstr "" + +#: ../../tutorials/installable-code.md:261 +msgid "Your project directory should now look like this:" +msgstr "" + +#: ../../tutorials/installable-code.md:271 +msgid "Step 3: Add code to your module" +msgstr "" + +#: ../../tutorials/installable-code.md:273 +msgid "" +"If you are following along and making a Python package from scratch then " +"you can add the code below to your `add_numbers.py` module. The function " +"below adds two integers together and returns the result. Notice that the " +"code below has a few features that we will review in future tutorials:" +msgstr "" + +#: ../../tutorials/installable-code.md:275 +msgid "It has a [numpy-style docstring](numpy-docstring)" +msgstr "" + +#: ../../tutorials/installable-code.md:276 +msgid "It uses [typing](type-hints)" +msgstr "" + +#: ../../tutorials/installable-code.md:278 +msgid "" +"Python can support many different docstrings formats depending on the " +"documentation build system you wish to use. The most popular supported " +"formats for documenting Python objects are NumPy Style " +"Docstring[^numpydoc], Google Style Docstring[^googledoc], and the Epytext" +" Style Docstrings[^epytextdoc]." +msgstr "" + +#: ../../tutorials/installable-code.md:280 +msgid "**pyOpenSci recommends using the NumPy Docstring convention.**" +msgstr "" + +#: ../../tutorials/installable-code.md:282 +msgid "" +"If you aren’t familiar with docstrings or typing yet, that is ok. You can" +" review [this page in the pyOpenSci packaging " +"guide](https://www.pyopensci.org/python-package-guide/documentation" +"/write-user-documentation/document-your-code-api-docstrings.html) for an " +"overview of both topics." +msgstr "" + +#: ../../tutorials/installable-code.md:311 +msgid "Step 4: Modify metadata in your `pyproject.toml` file" +msgstr "" + +#: ../../tutorials/installable-code.md:313 +msgid "" +"Next, you will modify some of the metadata (information) that Hatch adds " +"to your `pyproject.toml` file. You are are welcome to copy the file we " +"have in our [example pyospackage GitHub " +"repository](https://github.com/pyOpenSci/pyosPackage)." +msgstr "" + +#: ../../tutorials/installable-code.md:317 +msgid "Brief overview of the TOML file" +msgstr "" + +#: ../../tutorials/installable-code.md:320 +msgid "" +"[The TOML format](https://toml.io/en/) consists of tables and variables. " +"Tables are sections of information denoted by square brackets:" +msgstr "" + +#: ../../tutorials/installable-code.md:322 +msgid "`[this-is-a-table]`." +msgstr "" + +#: ../../tutorials/installable-code.md:324 +msgid "" +"Tables can contain variables within them defined by an variable name and " +"an `=` sign. For instance, a `build-system` table most often holds two " +"(2) variables:" +msgstr "" + +#: ../../tutorials/installable-code.md:327 +msgid "" +"`requires = `, which tells a build tool what tools it needs to install " +"prior to building your package. In this case " +"[hatchling](https://pypi.org/project/hatchling/)" +msgstr "" + +#: ../../tutorials/installable-code.md:329 +msgid "" +"`build-backend = `, which is used to define the specific build-backend " +"name, (in this example we are using `hatchling.build`)." +msgstr "" + +#: ../../tutorials/installable-code.md:338 +msgid "" +"TOML organizes data structures, defining relationships within a " +"configuration file." +msgstr "" + +#: ../../tutorials/installable-code.md:341 +msgid "" +"[Learn more about the pyproject.toml format here.](../package-structure-" +"code/pyproject-toml-python-package-metadata)" +msgstr "" + +#: ../../tutorials/installable-code.md:345 +msgid "" +"You will learn more about the `pyproject.toml` format in the [next lesson" +" when you add additional metadata / information to this file.](pyproject-" +"toml.md)" +msgstr "" + +#: ../../tutorials/installable-code.md:348 +msgid "" +"Open up the `pyproject.toml` file that Hatch created in your favorite " +"text editor. It should look something like the example below." +msgstr "" + +#: ../../tutorials/installable-code.md:390 +msgid "Edit the file as follows:" +msgstr "" + +#: ../../tutorials/installable-code.md:392 +msgid "" +"Delete `dynamic = [\"version\"]`: This sets up dynamic versioning based " +"on tags stored in your git commit history. We will walk through " +"implementing this in a later lesson." +msgstr "" + +#: ../../tutorials/installable-code.md:393 +msgid "" +"Add `version = \"0.1\"` in the place of `dynamic = [\"version\"]` which " +"you just deleted. This sets up manual versioning." +msgstr "" + +#: ../../tutorials/installable-code.md:394 +msgid "Fill in the description if it doesn't already exist." +msgstr "" + +#: ../../tutorials/installable-code.md:404 +msgid "Remove the `[tool.hatch.version]` table from the bottom of the file." +msgstr "" + +#: ../../tutorials/installable-code.md:412 +msgid "" +"When this lesson exists, uncomment this admonition You will learn how to " +"automate defining a package version using git tags in the version and " +"release your package lesson." +msgstr "" + +#: ../../tutorials/installable-code.md:417 +msgid "OPTIONAL: Adjust project classifiers" +msgstr "" + +#: ../../tutorials/installable-code.md:419 +msgid "" +"Hatch by default provides a list of classifiers that define what Python " +"versions your package supports. These classifiers do not in any way " +"impact your package's build and are primarily intended to be used when " +"you publish your package to PyPI." +msgstr "" + +#: ../../tutorials/installable-code.md:424 +msgid "" +"If you don't plan on publishing to PyPI, you can skip this section. " +"However, if you wish, you can clean it up a bit." +msgstr "" + +#: ../../tutorials/installable-code.md:427 +msgid "To begin:" +msgstr "" + +#: ../../tutorials/installable-code.md:429 +msgid "Remove support for Python 3.8" +msgstr "" + +#: ../../tutorials/installable-code.md:430 +msgid "" +"Within the `[project]` table, update `requires-python = \">3.8\"` to " +"`requires-python = \">3.9\"`" +msgstr "" + +#: ../../tutorials/installable-code.md:432 +msgid "" +"Since you are creating a pure Python package in this lesson, you can " +"remove the following classifiers:" +msgstr "" + +#: ../../tutorials/installable-code.md:442 +msgid "Your new pyproject.toml file should now look something like this:" +msgstr "" + +#: ../../tutorials/installable-code.md:477 +msgid "The bare minimum needed in a pyproject.toml file" +msgstr "" + +#: ../../tutorials/installable-code.md:480 +msgid "" +"The core information that you need in a `pyproject.toml` file in order to" +" publish on PyPI is your **package's name** and the **version**. " +"However, we suggest that you flesh out your metadata early on in the " +"`pyproject.toml` file." +msgstr "" + +#: ../../tutorials/installable-code.md:482 +msgid "" +"Once you have your project metadata in the pyproject.toml file, you will " +"rarely update it. In the next lesson you’ll add more metadata and " +"structure to this file." +msgstr "" + +#: ../../tutorials/installable-code.md:486 +msgid "Step 5: Install your package locally" +msgstr "" + +#: ../../tutorials/installable-code.md:488 +msgid "At this point you should have:" +msgstr "" + +#: ../../tutorials/installable-code.md:490 +msgid "A project directory structure with a `pyproject.toml` file at the root" +msgstr "" + +#: ../../tutorials/installable-code.md:491 +msgid "A package directory containing an empty `__init__.py` file and" +msgstr "" + +#: ../../tutorials/installable-code.md:492 +msgid "At least one Python module (e.g. `add_numbers.py`)" +msgstr "" + +#: ../../tutorials/installable-code.md:494 +msgid "You are now ready to install (and build) your Python package!" +msgstr "" + +#: ../../tutorials/installable-code.md:496 +msgid "" +"While you can do this using hatch, we are going to use pip for this " +"lesson, so you can see how to install your tool into your preferred " +"environment." +msgstr "" + +#: ../../tutorials/installable-code.md:498 +msgid "" +"First open your preferred shell (Windows users may be using something " +"like gitbash) and `cd` into your project directory if you are not already" +" there." +msgstr "" + +#: ../../tutorials/installable-code.md:499 +msgid "Activate the Python environment that you wish to use." +msgstr "" + +#: ../../tutorials/installable-code.md:500 +msgid "Run `python -m pip install -e .`" +msgstr "" + +#: ../../tutorials/installable-code.md:503 +msgid "Add this back in when the lesson is published" +msgstr "" + +#: ../../tutorials/installable-code.md:504 +msgid "" +"Activate the Python environment that you wish to use. If you need help " +"with working with virtual environments check out this lesson (add link)." +msgstr "" + +#: ../../tutorials/installable-code.md:530 +msgid "What does `python -m pip install -e .` do?" +msgstr "" + +#: ../../tutorials/installable-code.md:533 +msgid "Let's break down `python -m pip install -e .`" +msgstr "" + +#: ../../tutorials/installable-code.md:535 +msgid "" +"`python -m pip install -e .` installs your package into the current " +"active Python environment in **editable mode** (`-e`). Installing your " +"package in editable mode, allows you to work on your code and then test " +"the updates interactively in your favorite Python interface. One " +"important caveat of editable mode is that every time you update your " +"code, you may need to restart Python." +msgstr "" + +#: ../../tutorials/installable-code.md:540 +msgid "" +"If you wish to install the package regularly (not in editable mode) you " +"can use:" +msgstr "" + +#: ../../tutorials/installable-code.md:543 +msgid "`python -m pip install . `" +msgstr "" + +#: ../../tutorials/installable-code.md:545 +msgid "**Using `python -m` when calling `pip`**" +msgstr "" + +#: ../../tutorials/installable-code.md:547 +msgid "" +"Above, you use`python -m` to call the version of pip installed into your " +"current active environment. `python -m` is important to ensure that you " +"are calling the version of pip installed in your current environment." +msgstr "" + +#: ../../tutorials/installable-code.md:552 +msgid "Look for pyospackage in your environment" +msgstr "" + +#: ../../tutorials/installable-code.md:554 +msgid "" +"Once you have installed your package, you can view it in your current " +"environment. If you are using `venv` or `conda`, `pip` list will allow " +"you to see your current package installations." +msgstr "" + +#: ../../tutorials/installable-code.md:558 +msgid "" +"Note that because pyospackage is installed in editable mode (`-e`) pip " +"will show you the directory path to your project's code" +msgstr "" + +#: ../../tutorials/installable-code.md:586 +msgid "Step 6: Test out your new package" +msgstr "" + +#: ../../tutorials/installable-code.md:588 +msgid "" +"After installing your package, type “python” at the command prompt in " +"your chosen terminal to start a Python session in your active Python " +"environment." +msgstr "" + +#: ../../tutorials/installable-code.md:591 +msgid "You can now import your package and access the `add_num` function." +msgstr "" + +#: ../../tutorials/installable-code.md:603 +msgid "Installing packages from GitHub" +msgstr "" + +#: ../../tutorials/installable-code.md:605 +msgid "" +"If you wish to share your code without publishing to PyPI you can always " +"install packages directly from GitHub using the syntax:" +msgstr "" + +#: ../../tutorials/installable-code.md:612 +msgid "To make your package GitHub installable, you can:" +msgstr "" + +#: ../../tutorials/installable-code.md:614 +msgid "Create a new GitHub repository" +msgstr "" + +#: ../../tutorials/installable-code.md:615 +msgid "" +"Push the contents of the project directory that you created above, to " +"GitHub" +msgstr "" + +#: ../../tutorials/installable-code.md:616 +msgid "" +"Finally install the package from GitHub using the command above. When you" +" use the command above, don't forget to substitute the user, repo, and " +"branch_or_tag with your specific values." +msgstr "" + +#: ../../tutorials/installable-code.md:618 +msgid "" +"For instance below you install the pyospackage from the main branch of " +"the pyOpenSci repository." +msgstr "" + +#: ../../tutorials/installable-code.md:621 +msgid "`python -m pip install git+https://github.com/user/repo.git@branch_or_tag`" +msgstr "" + +#: ../../tutorials/installable-code.md:625 +msgid "Congratulations! You created your first Python package" +msgstr "" + +#: ../../tutorials/installable-code.md:627 +msgid "" +"You did it! You have now created a Python package that you can install " +"into any Python environment." +msgstr "" + +#: ../../tutorials/installable-code.md:630 +msgid "In the upcoming lessons you will:" +msgstr "" + +#: ../../tutorials/installable-code.md:632 +msgid "" +"Learn how to [build and publish your Python package to (test) PyPI" +"](publish-pypi)" +msgstr "" + +#: ../../tutorials/installable-code.md:633 +msgid "Add a README file and LICENSE to your package" +msgstr "" + +#: ../../tutorials/installable-code.md:634 +msgid "" +"Add more metadata to your `pyproject.toml` file to support PyPI " +"publication." +msgstr "" + +#: ../../tutorials/installable-code.md:635 +msgid "learn how to publish to **conda-forge** from **PyPI**." +msgstr "" + +#: ../../tutorials/installable-code.md:637 +msgid "" +"Add a [README file](add-readme.md) and [LICENSE](add-license-coc.md) to " +"your package" +msgstr "" + +#: ../../tutorials/installable-code.md:638 +msgid "" +"[Add more metadata to your `pyproject.toml`](pyproject-toml.md) file to " +"support PyPI publication." +msgstr "" + +#: ../../tutorials/installable-code.md:639 +msgid "" +"[Learn how to build your package distribution](publish-pypi) files " +"(**sdist** and **wheel**) and publish to **test PyPI**." +msgstr "" + +#: ../../tutorials/installable-code.md:640 +msgid "" +"Finally you will learn how to [publish to **conda-forge**](publish-conda-" +"forge) from **PyPI**." +msgstr "" + +#: ../../tutorials/installable-code.md:644 +msgid "[Carpentries shell lesson](https://swcarpentry.github.io/shell-novice/)" +msgstr "" + +#: ../../tutorials/installable-code.md:646 +msgid "" +"[Python module " +"docs](https://docs.python.org/3/tutorial/modules.html#packages)" +msgstr "" + +#: ../../tutorials/installable-code.md:648 +msgid "[Numpy style docs](https://numpydoc.readthedocs.io/en/latest/format.html)" +msgstr "" + +#: ../../tutorials/installable-code.md:647 +msgid "[Google docstring style](https://google.github.io/styleguide/pyguide.html)" +msgstr "" + +#: ../../tutorials/installable-code.md:649 +msgid "[epydoc](https://epydoc.sourceforge.net/epytext.html)" +msgstr "" + +#: ../../tutorials/intro.md:27 ../../tutorials/setup-py-to-pyproject-toml.md:24 +msgid "Get to know Hatch" +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 "" + From 9a4c4a112ab1f5a5995797e04f555fb7ccfb26d9 Mon Sep 17 00:00:00 2001 From: Tetsuo Koyama Date: Fri, 2 Aug 2024 18:25:20 +0900 Subject: [PATCH 6/8] Preparing the Translation Files for Japanese --- noxfile.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/noxfile.py b/noxfile.py index 4a0ea835..8ce321c4 100644 --- a/noxfile.py +++ b/noxfile.py @@ -43,7 +43,7 @@ ## Localization options (translations) # List of languages for which locales will be generated in (/locales/) -LANGUAGES = ["es"] +LANGUAGES = ["es", "jp"] # List of languages that should be built when releasing the guide (docs or docs-test sessions) RELEASE_LANGUAGES = [] From cd9004e222f02ee283d15c4b7dd8ca15db4170c9 Mon Sep 17 00:00:00 2001 From: Tetsuo Koyama Date: Fri, 2 Aug 2024 19:12:24 +0900 Subject: [PATCH 7/8] Following IETF language tag --- locales/{jp => ja}/LC_MESSAGES/CONTRIBUTING.po | 6 ++++-- locales/{jp => ja}/LC_MESSAGES/TRANSLATING.po | 6 ++++-- locales/{jp => ja}/LC_MESSAGES/documentation.po | 6 ++++-- locales/{jp => ja}/LC_MESSAGES/index.po | 6 ++++-- locales/{jp => ja}/LC_MESSAGES/package-structure-code.po | 6 ++++-- locales/{jp => ja}/LC_MESSAGES/tests.po | 6 ++++-- locales/{jp => ja}/LC_MESSAGES/tutorials.po | 6 ++++-- noxfile.py | 2 +- 8 files changed, 29 insertions(+), 15 deletions(-) rename locales/{jp => ja}/LC_MESSAGES/CONTRIBUTING.po (99%) rename locales/{jp => ja}/LC_MESSAGES/TRANSLATING.po (99%) rename locales/{jp => ja}/LC_MESSAGES/documentation.po (99%) rename locales/{jp => ja}/LC_MESSAGES/index.po (99%) rename locales/{jp => ja}/LC_MESSAGES/package-structure-code.po (99%) rename locales/{jp => ja}/LC_MESSAGES/tests.po (99%) rename locales/{jp => ja}/LC_MESSAGES/tutorials.po (99%) diff --git a/locales/jp/LC_MESSAGES/CONTRIBUTING.po b/locales/ja/LC_MESSAGES/CONTRIBUTING.po similarity index 99% rename from locales/jp/LC_MESSAGES/CONTRIBUTING.po rename to locales/ja/LC_MESSAGES/CONTRIBUTING.po index c30496e6..3c3eee6f 100644 --- a/locales/jp/LC_MESSAGES/CONTRIBUTING.po +++ b/locales/ja/LC_MESSAGES/CONTRIBUTING.po @@ -12,8 +12,9 @@ msgstr "" "POT-Creation-Date: 2024-08-02 18:04+0900\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" -"Language: jp\n" -"Language-Team: jp \n" +"Language: ja\n" +"Language-Team: ja \n" +"Plural-Forms: nplurals=1; plural=0;\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=utf-8\n" "Content-Transfer-Encoding: 8bit\n" @@ -432,3 +433,4 @@ msgstr "" #: ../../CONTRIBUTING.md:203 msgid "an example could be extracted from an existing toml file" msgstr "" + diff --git a/locales/jp/LC_MESSAGES/TRANSLATING.po b/locales/ja/LC_MESSAGES/TRANSLATING.po similarity index 99% rename from locales/jp/LC_MESSAGES/TRANSLATING.po rename to locales/ja/LC_MESSAGES/TRANSLATING.po index 08fd6165..707de067 100644 --- a/locales/jp/LC_MESSAGES/TRANSLATING.po +++ b/locales/ja/LC_MESSAGES/TRANSLATING.po @@ -12,8 +12,9 @@ msgstr "" "POT-Creation-Date: 2024-08-02 18:04+0900\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" -"Language: jp\n" -"Language-Team: jp \n" +"Language: ja\n" +"Language-Team: ja \n" +"Plural-Forms: nplurals=1; plural=0;\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=utf-8\n" "Content-Transfer-Encoding: 8bit\n" @@ -714,3 +715,4 @@ msgid "" " as a way for contributors to ask for help with translations or the " "translation workflow?" msgstr "" + diff --git a/locales/jp/LC_MESSAGES/documentation.po b/locales/ja/LC_MESSAGES/documentation.po similarity index 99% rename from locales/jp/LC_MESSAGES/documentation.po rename to locales/ja/LC_MESSAGES/documentation.po index 110015b6..8a849f4a 100644 --- a/locales/jp/LC_MESSAGES/documentation.po +++ b/locales/ja/LC_MESSAGES/documentation.po @@ -12,8 +12,9 @@ msgstr "" "POT-Creation-Date: 2024-08-02 18:04+0900\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" -"Language: jp\n" -"Language-Team: jp \n" +"Language: ja\n" +"Language-Team: ja \n" +"Plural-Forms: nplurals=1; plural=0;\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=utf-8\n" "Content-Transfer-Encoding: 8bit\n" @@ -2542,3 +2543,4 @@ msgstr "" #: ../../documentation/write-user-documentation/intro.md:15 msgid "sphinx gallery for tutorials." msgstr "" + diff --git a/locales/jp/LC_MESSAGES/index.po b/locales/ja/LC_MESSAGES/index.po similarity index 99% rename from locales/jp/LC_MESSAGES/index.po rename to locales/ja/LC_MESSAGES/index.po index 6a5d16e1..6d662248 100644 --- a/locales/jp/LC_MESSAGES/index.po +++ b/locales/ja/LC_MESSAGES/index.po @@ -12,8 +12,9 @@ msgstr "" "POT-Creation-Date: 2024-08-02 18:04+0900\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" -"Language: jp\n" -"Language-Team: jp \n" +"Language: ja\n" +"Language-Team: ja \n" +"Plural-Forms: nplurals=1; plural=0;\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=utf-8\n" "Content-Transfer-Encoding: 8bit\n" @@ -480,3 +481,4 @@ msgid "" " in the Python packaging ecosystem. We will be adding new content over " "the next year." msgstr "" + diff --git a/locales/jp/LC_MESSAGES/package-structure-code.po b/locales/ja/LC_MESSAGES/package-structure-code.po similarity index 99% rename from locales/jp/LC_MESSAGES/package-structure-code.po rename to locales/ja/LC_MESSAGES/package-structure-code.po index 5848b446..e409630c 100644 --- a/locales/jp/LC_MESSAGES/package-structure-code.po +++ b/locales/ja/LC_MESSAGES/package-structure-code.po @@ -12,8 +12,9 @@ msgstr "" "POT-Creation-Date: 2024-08-02 18:04+0900\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" -"Language: jp\n" -"Language-Team: jp \n" +"Language: ja\n" +"Language-Team: ja \n" +"Plural-Forms: nplurals=1; plural=0;\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=utf-8\n" "Content-Transfer-Encoding: 8bit\n" @@ -5298,3 +5299,4 @@ 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/jp/LC_MESSAGES/tests.po b/locales/ja/LC_MESSAGES/tests.po similarity index 99% rename from locales/jp/LC_MESSAGES/tests.po rename to locales/ja/LC_MESSAGES/tests.po index dfea8e3f..540e03ab 100644 --- a/locales/jp/LC_MESSAGES/tests.po +++ b/locales/ja/LC_MESSAGES/tests.po @@ -12,8 +12,9 @@ msgstr "" "POT-Creation-Date: 2024-08-02 18:04+0900\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" -"Language: jp\n" -"Language-Team: jp \n" +"Language: ja\n" +"Language-Team: ja \n" +"Plural-Forms: nplurals=1; plural=0;\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=utf-8\n" "Content-Transfer-Encoding: 8bit\n" @@ -999,3 +1000,4 @@ msgid "" "the user can easily understand why if failed (provides a useful error " "message)." msgstr "" + diff --git a/locales/jp/LC_MESSAGES/tutorials.po b/locales/ja/LC_MESSAGES/tutorials.po similarity index 99% rename from locales/jp/LC_MESSAGES/tutorials.po rename to locales/ja/LC_MESSAGES/tutorials.po index e162ef1e..6f88c534 100644 --- a/locales/jp/LC_MESSAGES/tutorials.po +++ b/locales/ja/LC_MESSAGES/tutorials.po @@ -12,8 +12,9 @@ msgstr "" "POT-Creation-Date: 2024-08-02 18:04+0900\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" -"Language: jp\n" -"Language-Team: jp \n" +"Language: ja\n" +"Language-Team: ja \n" +"Plural-Forms: nplurals=1; plural=0;\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=utf-8\n" "Content-Transfer-Encoding: 8bit\n" @@ -5533,3 +5534,4 @@ msgid "" "existing functionality remains intact. Run any pre-existing tests to " "verify that everything still works as expected." msgstr "" + diff --git a/noxfile.py b/noxfile.py index 8ce321c4..ee44f29c 100644 --- a/noxfile.py +++ b/noxfile.py @@ -43,7 +43,7 @@ ## Localization options (translations) # List of languages for which locales will be generated in (/locales/) -LANGUAGES = ["es", "jp"] +LANGUAGES = ["es", "ja"] # List of languages that should be built when releasing the guide (docs or docs-test sessions) RELEASE_LANGUAGES = [] From b336a4ee910da4be8b53f40dce60e9b1b32b569d Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 2 Aug 2024 10:25:13 +0000 Subject: [PATCH 8/8] =?UTF-8?q?'[pre-commit.ci=20=F0=9F=A4=96]=20Apply=20c?= =?UTF-8?q?ode=20format=20tools=20to=20PR'?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- locales/ja/LC_MESSAGES/CONTRIBUTING.po | 1 - locales/ja/LC_MESSAGES/TRANSLATING.po | 1 - locales/ja/LC_MESSAGES/documentation.po | 1 - locales/ja/LC_MESSAGES/index.po | 1 - locales/ja/LC_MESSAGES/package-structure-code.po | 1 - locales/ja/LC_MESSAGES/tests.po | 1 - locales/ja/LC_MESSAGES/tutorials.po | 1 - 7 files changed, 7 deletions(-) diff --git a/locales/ja/LC_MESSAGES/CONTRIBUTING.po b/locales/ja/LC_MESSAGES/CONTRIBUTING.po index 3c3eee6f..16c831c9 100644 --- a/locales/ja/LC_MESSAGES/CONTRIBUTING.po +++ b/locales/ja/LC_MESSAGES/CONTRIBUTING.po @@ -433,4 +433,3 @@ msgstr "" #: ../../CONTRIBUTING.md:203 msgid "an example could be extracted from an existing toml file" msgstr "" - diff --git a/locales/ja/LC_MESSAGES/TRANSLATING.po b/locales/ja/LC_MESSAGES/TRANSLATING.po index 707de067..13765fc7 100644 --- a/locales/ja/LC_MESSAGES/TRANSLATING.po +++ b/locales/ja/LC_MESSAGES/TRANSLATING.po @@ -715,4 +715,3 @@ msgid "" " as a way for contributors to ask for help with translations or the " "translation workflow?" msgstr "" - diff --git a/locales/ja/LC_MESSAGES/documentation.po b/locales/ja/LC_MESSAGES/documentation.po index 8a849f4a..ea6bdd72 100644 --- a/locales/ja/LC_MESSAGES/documentation.po +++ b/locales/ja/LC_MESSAGES/documentation.po @@ -2543,4 +2543,3 @@ msgstr "" #: ../../documentation/write-user-documentation/intro.md:15 msgid "sphinx gallery for tutorials." msgstr "" - diff --git a/locales/ja/LC_MESSAGES/index.po b/locales/ja/LC_MESSAGES/index.po index 6d662248..379d9450 100644 --- a/locales/ja/LC_MESSAGES/index.po +++ b/locales/ja/LC_MESSAGES/index.po @@ -481,4 +481,3 @@ msgid "" " in the Python packaging ecosystem. We will be adding new content over " "the next year." msgstr "" - diff --git a/locales/ja/LC_MESSAGES/package-structure-code.po b/locales/ja/LC_MESSAGES/package-structure-code.po index e409630c..f02e7e1e 100644 --- a/locales/ja/LC_MESSAGES/package-structure-code.po +++ b/locales/ja/LC_MESSAGES/package-structure-code.po @@ -5299,4 +5299,3 @@ 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/ja/LC_MESSAGES/tests.po b/locales/ja/LC_MESSAGES/tests.po index 540e03ab..1b5994c6 100644 --- a/locales/ja/LC_MESSAGES/tests.po +++ b/locales/ja/LC_MESSAGES/tests.po @@ -1000,4 +1000,3 @@ msgid "" "the user can easily understand why if failed (provides a useful error " "message)." msgstr "" - diff --git a/locales/ja/LC_MESSAGES/tutorials.po b/locales/ja/LC_MESSAGES/tutorials.po index 6f88c534..7eb0df48 100644 --- a/locales/ja/LC_MESSAGES/tutorials.po +++ b/locales/ja/LC_MESSAGES/tutorials.po @@ -5534,4 +5534,3 @@ msgid "" "existing functionality remains intact. Run any pre-existing tests to " "verify that everything still works as expected." msgstr "" -