|
1 | | -# setuptools-scm |
2 | | -[](https://github.com/pypa/setuptools-scm/actions/workflows/python-tests.yml) |
3 | | -[](https://setuptools-scm.readthedocs.io/en/latest/?badge=latest) |
4 | | -[ ](https://tidelift.com/subscription/pkg/pypi-setuptools-scm?utm_source=pypi-setuptools-scm&utm_medium=readme) |
| 1 | +# setuptools-scm Monorepo |
5 | 2 |
|
6 | | -## about |
| 3 | +This is the monorepo for the setuptools-scm ecosystem, containing two main projects: |
7 | 4 |
|
8 | | -[setuptools-scm] extracts Python package versions from `git` or `hg` metadata |
9 | | -instead of declaring them as the version argument |
10 | | -or in a Source Code Managed (SCM) managed file. |
| 5 | +## Projects |
11 | 6 |
|
12 | | -Additionally [setuptools-scm] provides `setuptools` with a list of |
13 | | -files that are managed by the SCM |
14 | | -<br/> |
15 | | -(i.e. it automatically adds all the SCM-managed files to the sdist). |
16 | | -<br/> |
17 | | -Unwanted files must be excluded via `MANIFEST.in` |
18 | | -or [configuring Git archive][git-archive-docs]. |
| 7 | +### [setuptools-scm](./setuptools-scm/) |
19 | 8 |
|
20 | | -> **⚠️ Important:** Installing setuptools-scm automatically enables a file finder that includes **all SCM-tracked files** in your source distributions. This can be surprising if you have development files tracked in Git/Mercurial that you don't want in your package. Use `MANIFEST.in` to exclude unwanted files. See the [documentation] for details. |
| 9 | +The main package that extracts Python package versions from Git or Mercurial metadata and provides setuptools integration. |
21 | 10 |
|
22 | | -## `pyproject.toml` usage |
| 11 | +**[Read setuptools-scm documentation →](./setuptools-scm/README.md)** |
23 | 12 |
|
24 | | -The preferred way to configure [setuptools-scm] is to author |
25 | | -settings in a `tool.setuptools_scm` section of `pyproject.toml`. |
| 13 | +### [vcs-versioning](./vcs-versioning/) |
26 | 14 |
|
27 | | -This feature requires setuptools 61 or later (recommended: >=80 for best compatibility). |
28 | | -First, ensure that [setuptools-scm] is present during the project's |
29 | | -build step by specifying it as one of the build requirements. |
| 15 | +Core VCS versioning functionality extracted as a standalone library that can be used independently of setuptools. |
30 | 16 |
|
31 | | -```toml title="pyproject.toml" |
32 | | -[build-system] |
33 | | -requires = ["setuptools>=80", "setuptools-scm>=8"] |
34 | | -build-backend = "setuptools.build_meta" |
35 | | -``` |
36 | | - |
37 | | -That will be sufficient to require [setuptools-scm] for projects |
38 | | -that support [PEP 518] like [pip] and [build]. |
39 | | - |
40 | | -[pip]: https://pypi.org/project/pip |
41 | | -[build]: https://pypi.org/project/build |
42 | | -[PEP 518]: https://peps.python.org/pep-0518/ |
43 | | - |
44 | | - |
45 | | -To enable version inference, you need to set the version |
46 | | -dynamically in the `project` section of `pyproject.toml`: |
| 17 | +**[Read vcs-versioning documentation →](./vcs-versioning/README.md)** |
47 | 18 |
|
48 | | -```toml title="pyproject.toml" |
49 | | -[project] |
50 | | -# version = "0.0.1" # Remove any existing version parameter. |
51 | | -dynamic = ["version"] |
| 19 | +## Development |
52 | 20 |
|
53 | | -[tool.setuptools_scm] |
54 | | -``` |
55 | | - |
56 | | -!!! note "Simplified Configuration" |
57 | | - |
58 | | - Starting with setuptools-scm 8.1+, if `setuptools_scm` (or `setuptools-scm`) is |
59 | | - present in your `build-system.requires`, the `[tool.setuptools_scm]` section |
60 | | - becomes optional! You can now enable setuptools-scm with just: |
| 21 | +This workspace uses [uv](https://github.com/astral-sh/uv) for dependency management. |
61 | 22 |
|
62 | | - ```toml title="pyproject.toml" |
63 | | - [build-system] |
64 | | - requires = ["setuptools>=80", "setuptools-scm>=8"] |
65 | | - build-backend = "setuptools.build_meta" |
| 23 | +### Running Tests |
66 | 24 |
|
67 | | - [project] |
68 | | - dynamic = ["version"] |
69 | | - ``` |
| 25 | +```bash |
| 26 | +# Run all tests |
| 27 | +uv run pytest -n12 |
70 | 28 |
|
71 | | - The `[tool.setuptools_scm]` section is only needed if you want to customize |
72 | | - configuration options. |
| 29 | +# Run tests for setuptools-scm only |
| 30 | +uv run pytest setuptools-scm/testing_scm -n12 |
73 | 31 |
|
74 | | -Additionally, a version file can be written by specifying: |
75 | | - |
76 | | -```toml title="pyproject.toml" |
77 | | -[tool.setuptools_scm] |
78 | | -version_file = "pkg/_version.py" |
| 32 | +# Run tests for vcs-versioning only |
| 33 | +uv run pytest vcs-versioning/testing_vcs -n12 |
79 | 34 | ``` |
80 | 35 |
|
81 | | -Where `pkg` is the name of your package. |
| 36 | +### Building Documentation |
82 | 37 |
|
83 | | -If you need to confirm which version string is being generated or debug the configuration, |
84 | | -you can install [setuptools-scm] directly in your working environment and run: |
| 38 | +Documentation is shared across projects: |
85 | 39 |
|
86 | | -```console |
87 | | -$ python -m setuptools_scm |
88 | | -# To explore other options, try: |
89 | | -$ python -m setuptools_scm --help |
| 40 | +```bash |
| 41 | +uv run mkdocs serve |
90 | 42 | ``` |
91 | 43 |
|
92 | | -For further configuration see the [documentation]. |
93 | | - |
94 | | -[setuptools-scm]: https://github.com/pypa/setuptools-scm |
95 | | -[documentation]: https://setuptools-scm.readthedocs.io/ |
96 | | -[git-archive-docs]: https://setuptools-scm.readthedocs.io/en/stable/usage/#builtin-mechanisms-for-obtaining-version-numbers |
97 | | - |
98 | | - |
99 | | -## Interaction with Enterprise Distributions |
100 | | - |
101 | | -Some enterprise distributions like RHEL7 |
102 | | -ship rather old setuptools versions. |
103 | | - |
104 | | -In those cases its typically possible to build by using an sdist against `setuptools-scm<2.0`. |
105 | | -As those old setuptools versions lack sensible types for versions, |
106 | | -modern [setuptools-scm] is unable to support them sensibly. |
107 | | - |
108 | | -It's strongly recommended to build a wheel artifact using modern Python and setuptools, |
109 | | -then installing the artifact instead of trying to run against old setuptools versions. |
110 | | - |
111 | | -!!! note "Legacy Setuptools Support" |
112 | | - While setuptools-scm recommends setuptools >=80, it maintains compatibility with setuptools 61+ |
113 | | - to support legacy deployments that cannot easily upgrade. Support for setuptools <80 is deprecated |
114 | | - and will be removed in a future release. This allows enterprise environments and older CI/CD systems |
115 | | - to continue using setuptools-scm while still encouraging adoption of newer versions. |
116 | | - |
117 | | - |
118 | | -## Code of Conduct |
119 | | - |
120 | | - |
121 | | -Everyone interacting in the [setuptools-scm] project's codebases, issue |
122 | | -trackers, chat rooms, and mailing lists is expected to follow the |
123 | | -[PSF Code of Conduct]. |
| 44 | +## Links |
124 | 45 |
|
125 | | -[PSF Code of Conduct]: https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md |
| 46 | +- **Documentation**: https://setuptools-scm.readthedocs.io/ |
| 47 | +- **Repository**: https://github.com/pypa/setuptools-scm/ |
| 48 | +- **Issues**: https://github.com/pypa/setuptools-scm/issues |
126 | 49 |
|
| 50 | +## License |
127 | 51 |
|
128 | | -## Security Contact |
| 52 | +Both projects are distributed under the terms of the MIT license. |
129 | 53 |
|
130 | | -To report a security vulnerability, please use the |
131 | | -[Tidelift security contact](https://tidelift.com/security). |
132 | | -Tidelift will coordinate the fix and disclosure. |
0 commit comments