Skip to content

Commit 072cb8b

Browse files
willingcwillingc
authored
Merge pull request #635 from lwasser/glossary
feat: add glossary to packaging guide
2 parents e608cf4 + 3fc4f28 commit 072cb8b

15 files changed

Lines changed: 386 additions & 51 deletions

‎documentation/glossary.md‎

Lines changed: 257 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
---
2+
:og:title: Python packaging glossary
3+
:og:description: A glossary of common terms used across this Python package
4+
guide.
5+
---
6+
7+
# Python packaging glossary
8+
9+
## Core packaging
10+
11+
```{glossary}
12+
`__init__.py`
13+
A special Python file that marks a directory as a Python package.
14+
When Python sees this file, it knows the folder contains importable
15+
code. It can either be empty or contain code that runs when the package
16+
is imported.
17+
18+
API token
19+
A secret key used to authenticate with PyPI or TestPyPI when
20+
publishing a package. You generate one in your account settings and
21+
use it in place of a password. **Treat it like a password and never
22+
share it or commit it to version control**.
23+
24+
Build backend
25+
The tool that does the actual work of building your package into
26+
distribution files. In this guide, the build backend is Hatchling.
27+
You specify it in your `pyproject.toml` file under `[build-system]`.
28+
29+
You execute a build by running `hatch build`. Alternatively, you can run `python -m build`.
30+
[Reference: official Python Packaging documentation](https://packaging.python.org/en/latest/tutorials/packaging-projects/#choosing-a-build-backend)
31+
32+
Distribution files
33+
The files you upload to PyPI so others can install your package.
34+
There are two common types: a wheel (`.whl`) and a source
35+
distribution (`.tar.gz`). See also `Wheel (.whl)` and `Source
36+
distribution (sdist)`.
37+
38+
Module
39+
A single Python file (`.py`) containing code such as functions,
40+
classes, or variables that can be imported. A package is made up of
41+
one or more modules.
42+
43+
`pyproject.toml`
44+
The configuration file at the root of your Python package. Written in
45+
TOML format, it stores metadata such as name, version, authors, and
46+
license. It can also configure tools such as Hatch, uv, and pytest.
47+
See also [Make your Python package PyPI ready](../tutorials/pyproject-toml).
48+
49+
Python package
50+
A directory of Python code structured so it can be installed,
51+
imported, and shared with others. A package includes at least an
52+
`__init__.py` file and a `pyproject.toml` file. This is sometimes
53+
referred to as a **regular package**.
54+
55+
Info: You may hear the term **namespaced package** which is not really
56+
a package at all but a container of subpackages. This is out of scope
57+
for this guide. If interested, consult the [Python documentation](https://docs.python.org/3/glossary.html#term-namespace-package).
58+
59+
PyPI / TestPyPI
60+
PyPI (the Python Package Index) is the official repository where
61+
Python packages are published and installed from. TestPyPI is a
62+
separate practice environment used for learning and testing publishing
63+
workflows. See [pypi.org](https://pypi.org) and
64+
[test.pypi.org](https://test.pypi.org).
65+
See also [Publish your Python package to PyPI](../tutorials/publish-pypi).
66+
67+
Source distribution (sdist)
68+
One of the two distribution file types for a Python package. The
69+
sdist (`.tar.gz`) contains source code and project files. When someone
70+
installs from an sdist, tools build the package locally first.
71+
See also [Publish your Python package to PyPI](../tutorials/publish-pypi).
72+
73+
TOML
74+
Tom's Obvious Minimal Language, a simple format for configuration
75+
files. TOML organizes data into tables such as `[project]` or
76+
`[tool.hatch]` and arrays. `pyproject.toml` uses TOML.
77+
78+
Trusted publishing
79+
A secure way to publish to PyPI using GitHub Actions instead of an
80+
API token. Rather than storing a secret token, you configure PyPI to
81+
trust your repository directly.
82+
See also [Setup Trusted Publishing for secure and automated publishing via GitHub Actions](../tutorials/trusted-publishing).
83+
84+
Wheel (.whl)
85+
The binary distribution type for a Python package. A wheel
86+
is a pre-built binary format (`.whl`, a ZIP file) that installs directly
87+
without a build step. For many pure Python packages, one wheel can
88+
work across platforms.
89+
See also [Publish your Python package to PyPI](../tutorials/publish-pypi).
90+
```
91+
92+
## Tools
93+
94+
```{glossary}
95+
copier
96+
A command-line tool for creating new projects from templates. In this
97+
guide, you can use copier with the pyOpenSci package template to set
98+
up structure, configuration, and tooling quickly. See
99+
[copier.readthedocs.io](https://copier.readthedocs.io).
100+
101+
coverage.py
102+
A tool that measures how much of your code is exercised by tests,
103+
often as a percentage. It shows which lines and branches are covered.
104+
See [coverage.readthedocs.io](https://coverage.readthedocs.io).
105+
106+
Hatch
107+
A modern Python packaging and project management tool. In this guide,
108+
Hatch is used to build packages, manage environments, run scripts, and
109+
publish. Configuration lives in `pyproject.toml`. See
110+
[hatch.pypa.io](https://hatch.pypa.io).
111+
See also [Get to know Hatch](../tutorials/get-to-know-hatch).
112+
113+
Hatchling
114+
The build backend used by Hatch. When you run `python -m build` or
115+
`hatch build`, Hatchling reads `pyproject.toml` and creates sdist
116+
and wheel files.
117+
See [hatch.pypa.io/latest/backend](https://hatch.pypa.io/latest/backend/).
118+
119+
pip
120+
Python's default package installer. You can use it to install packages
121+
from PyPI into an environment with commands such as
122+
`pip install package-name`. See [pip.pypa.io](https://pip.pypa.io).
123+
124+
pytest
125+
A widely used Python testing framework for discovering and running tests.
126+
In this guide, pytest often runs through Hatch scripts. See
127+
[docs.pytest.org](https://docs.pytest.org).
128+
129+
Ruff
130+
A fast Python linter and formatter. It checks style and can
131+
automatically fix many styling issues. See
132+
[docs.astral.sh/ruff](https://docs.astral.sh/ruff).
133+
134+
Sphinx
135+
A documentation generator for Python projects. Sphinx reads docstrings
136+
and documentation files to build a docs site. See
137+
[sphinx-doc.org](https://www.sphinx-doc.org).
138+
139+
Twine
140+
A tool for securely uploading distribution files to PyPI or TestPyPI.
141+
See [twine.readthedocs.io](https://twine.readthedocs.io).
142+
143+
uv
144+
A fast Python package and environment manager. In this guide, you can
145+
use uv to manage dependencies and run commands in project environments.
146+
See [docs.astral.sh/uv](https://docs.astral.sh/uv).
147+
```
148+
149+
## Hatch-specific concepts
150+
151+
```{glossary}
152+
Hatch environment
153+
An isolated Python environment managed by Hatch. You can define
154+
multiple environments in `pyproject.toml` for testing, docs, builds,
155+
and style checks, each with its own dependencies and scripts.
156+
157+
Script (Hatch)
158+
A named command defined inside a Hatch environment in
159+
`pyproject.toml`. Scripts provide shortcuts such as
160+
`hatch run build:check` and `hatch run test:run`.
161+
162+
Task runner
163+
A tool that automates repetitive development workflows. Hatch can
164+
function as a task runner by letting you define scripts that run in
165+
specific environments.
166+
```
167+
168+
## Development concepts
169+
170+
```{glossary}
171+
Code coverage
172+
A measure of how much source code executes during tests, usually as a
173+
percentage. High coverage does not guarantee no bugs, but low coverage
174+
can indicate untested areas.
175+
176+
Dependencies
177+
Other Python packages needed for your package to work. Common classes
178+
include required dependencies, optional dependencies, and development
179+
dependencies.
180+
181+
Docstring
182+
A string at the top of a function, class, or module that describes
183+
behavior, inputs, and outputs. Docstrings can be used by tools such as
184+
Sphinx to generate API documentation.
185+
186+
End-to-end test
187+
A test that simulates a complete user workflow from start to finish.
188+
In scientific packages, tutorials executed during docs builds can
189+
serve as end-to-end tests.
190+
191+
Integration test
192+
A test that checks how multiple functions or components work together.
193+
Unlike a unit test, it verifies behavior across a broader workflow.
194+
195+
Linting
196+
Automatic checks for style issues, formatting problems, and potential
197+
errors in code.
198+
199+
Unit test
200+
A test that checks one function or method in isolation. Unit tests are
201+
fast and help pinpoint where failures occur.
202+
203+
Version specifier / lower bound
204+
A constraint on which dependency versions are accepted. For example,
205+
`numpy>=1.24` sets a lower bound so versions older than 1.24 are not
206+
used.
207+
```
208+
209+
## Git / GitHub
210+
211+
```{glossary}
212+
git
213+
A tool for version control.
214+
215+
GitHub
216+
A service providing accounts and organizations to facilitate sharing repositories.
217+
218+
GitHub Codespace
219+
A cloud-based development environment that runs in a browser. See
220+
[github.com/features/codespaces](https://github.com/features/codespaces).
221+
222+
Scoped commit
223+
A git commit that makes one focused change, such as one fix or one
224+
feature update. Scoped commits improve reviewability and history
225+
clarity.
226+
```
227+
228+
## Documentation
229+
230+
```{glossary}
231+
Code of conduct
232+
A document that sets expectations for how contributors and community
233+
members treat one another in a project.
234+
235+
Contributing guide
236+
A document, often `CONTRIBUTING.md`, that explains how others can
237+
contribute, including setup steps, workflow, and code style.
238+
239+
MyST Markdown
240+
Markedly Structured Text, a Markdown flavor that supports Sphinx
241+
directives and roles. It allows Markdown-based docs while keeping
242+
Sphinx features. See
243+
[myst-parser.readthedocs.io](https://myst-parser.readthedocs.io).
244+
245+
README
246+
The front page of your package on GitHub and often on PyPI. A good
247+
README explains purpose, installation, usage, and support options.
248+
```
249+
250+
## AI
251+
252+
```{glossary}
253+
Generative AI / LLM
254+
Generative AI systems produce content such as text, code, or images.
255+
LLM stands for Large Language Model, the technology behind tools such
256+
as ChatGPT, GitHub Copilot, and Claude.
257+
```

‎index.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -320,3 +320,11 @@ Tests <tests/index>
320320
Maintain <maintain-automate/index>
321321

322322
:::
323+
324+
:::{toctree}
325+
:hidden:
326+
:caption: Reference
327+
328+
Glossary <documentation/glossary>
329+
330+
:::

‎tutorials/add-license-coc.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,10 @@ A license contains legal language about how users can use and reuse your softwar
2828
1. Create a `LICENSE` file in your project directory that specifies the license that you choose for your package.
2929
2. Describe your choice of license in your `pyproject.toml` data where metadata are set.
3030

31-
By adding this metadata to your `pyproject.toml` file, the choice of license will be included in your package's metadata which is used to populate your package's PyPI landing page. The `LICENSE` file is also used in your GitHub repository's landing page interface.
31+
By adding this metadata to your [pyproject.toml](pyproject-toml) file, the choice of
32+
license will be included in your package's metadata which is used to populate
33+
your package's PyPI landing page. The `LICENSE` file is also used in your
34+
GitHub repository's landing page interface, and makes its way into your distributions.
3235

3336
### What license should you use?
3437

@@ -143,7 +146,8 @@ package directory.
143146
(add-coc)=
144147
## What is a code of conduct file?
145148

146-
A `CODE_OF_CONDUCT` file is used to establish guidelines for how people in your community interact.
149+
A `CODE_OF_CONDUCT` file is a {term}`Code of conduct` used to establish
150+
guidelines for how people in your community interact.
147151

148152
This file is critical to supporting your community as it
149153
grows. The `CODE_OF_CONDUCT`:

‎tutorials/add-readme.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
:og:title: Add a README file to your Python package
44
---
55

6-
# Add a README file to your Python package
6+
# Add a {term}`README` file to your {term}`Python package`
77

88
In the previous lessons you learned:
99

@@ -22,7 +22,8 @@ In this lesson you will learn:
2222

2323
## What is a README file?
2424

25-
The `README.md` file is a markdown file located at the root of your project directory that helps
25+
The `README.md` file is the project's {term}`README` and is located at the
26+
root of your project directory. It helps
2627
a user understand:
2728

2829
- You package's name
@@ -93,7 +94,7 @@ Remember that the more people understand what your package does, the more people
9394

9495
Next, add instructions that tell users how to install your package.
9596

96-
For example, can they use pip to install your package?
97+
For example, can they use {term}`pip` to install your package?
9798
`python -m pip install packagename`
9899

99100
or conda?
@@ -160,7 +161,8 @@ help users understand how to use your package for common workflows.
160161
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.
161162

162163
In the community section, you will add links to your contributing guide
163-
and `CODE_OF_CONDUCT.md`. You will create a [`CODE_OF_CONDUCT.md` file in the next lesson](add-license-coc).
164+
and `CODE_OF_CONDUCT.md`. You will create a code of conduct file in the
165+
[next lesson](add-license-coc).
164166

165167
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
166168
outlines how to perform maintenance tasks such as:

‎tutorials/command-line-reference.md‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,14 @@
66
# Command Line Reference Guide
77

88
```{important}
9-
**What these tables are:** These tables summarize the command line inputs (e.g., `pipx install hatch`, `hatch build`) necessary to complete all steps in the package creation process, from installing Hatch to publishing the package on PyPI and conda-forge.
10-
11-
**What these tables are not:** These tables do not cover the manual/non-automated steps (e.g., create PyPI account, create PyPI API token) you have to complete throughout the package creation process.
9+
**What these tables are:** These tables summarize the command line inputs (e.g.,
10+
`pipx install hatch`, `hatch build` or `python -m build`) necessary to complete all steps in the
11+
package creation process, from installing [Hatch](get-to-know-hatch) to
12+
publishing the package on [PyPI](publish-pypi) and conda-forge.
13+
14+
**What these tables are not:** These tables do not cover the manual or
15+
non-automated steps (e.g., create a PyPI account, create a {term}`API token`)
16+
you have to complete throughout the package creation process.
1217
1318
**Operating system note:** The current iteration of this guide has been tested on the Windows OS only. Many commands are Windows-specific. OS-specific commands are indicated with parentheses after the description of the command, e.g., [COMMAND_DESCRIPTION] (Windows). Corresponding commands for macOS and Linux will be added in the future.
1419
```

0 commit comments

Comments
 (0)