Merge branch 'main' into version-file

Author: RonnyPfannschmidt

CHANGELOG.md

@@ -1,3 +1,8 @@
+# Unreleased
+
+## Changed
+
+- inclusion of `__all__` in autogenerated `version.py` files to aid IDE autoimports
 
 # v8.0.4
 
@@ -14,7 +19,7 @@
 
 - fix #925: allow `write_to` to be an absolute path when it's a subdirectory of the root
 - fix #932: ensure type annotations in version file don't cause linter issues
-- fix #930: temporary restore `DEFAULT_VERSION_SCHEME` and `DEFAULT_LOCAL_SCHEME` on the `setuptools_scm` package
+- fix #930: temporary restore `DEFAULT_VERSION_SCHEME` and `DEFAULT_LOCAL_SCHEME` on the `setuptools-scm` package
 
 
 
@@ -60,6 +65,7 @@
 - use normalized dist names for the `SETUPTOOLS_SCM_PRETEND_VERSION_FOR_${DIST_NAME}` env var
 - drop support for python 3.7
 - introduce `version_file` as replacement for `write_to`
+- renameed the project from `setuptools_scm` to `setuptools-scm`
 
 ## features
 

README.md

@@ -1,5 +1,5 @@
-# setuptools_scm
-[![github ci](https://github.com/pypa/setuptools_scm/actions/workflows/python-tests.yml/badge.svg)](https://github.com/pypa/setuptools_scm/actions/workflows/python-tests.yml)
+# setuptools-scm
+[![github ci](https://github.com/pypa/setuptools-scm/actions/workflows/python-tests.yml/badge.svg)](https://github.com/pypa/setuptools-scm/actions/workflows/python-tests.yml)
 [![Documentation Status](https://readthedocs.org/projects/setuptools-scm/badge/?version=latest)](https://setuptools-scm.readthedocs.io/en/latest/?badge=latest)
 [![tidelift](https://tidelift.com/badges/package/pypi/setuptools-scm) ](https://tidelift.com/subscription/pkg/pypi-setuptools-scm?utm_source=pypi-setuptools-scm&utm_medium=readme)
 
@@ -28,7 +28,7 @@ build step by specifying it as one of the build requirements.
 
 ```toml title="pyproject.toml"
 [build-system]
-requires = ["setuptools>=64", "setuptools_scm>=8"]
+requires = ["setuptools>=64", "setuptools-scm>=8"]
 build-backend = "setuptools.build_meta"
 ```
 
@@ -71,7 +71,7 @@ $ python -m setuptools_scm --help
 
 For further configuration see the [documentation].
 
-[setuptools-scm]: https://github.com/pypa/setuptools_scm
+[setuptools-scm]: https://github.com/pypa/setuptools-scm
 [documentation]: https://setuptools-scm.readthedocs.io/
 [git-archive-docs]: https://setuptools-scm.readthedocs.io/en/stable/usage/#builtin-mechanisms-for-obtaining-version-numbers
 
@@ -81,7 +81,7 @@ For further configuration see the [documentation].
 Some enterprise distributions like RHEL7
 ship rather old setuptools versions.
 
-In those cases its typically possible to build by using an sdist against `setuptools_scm<2.0`.
+In those cases its typically possible to build by using an sdist against `setuptools-scm<2.0`.
 As those old setuptools versions lack sensible types for versions,
 modern [setuptools-scm] is unable to support them sensibly.
 

docs/config.md

@@ -11,11 +11,13 @@ Callables or other Python objects have to be passed in `setup.py` (via the `use_
 : Relative path to the SCM root, defaults to `.` and is relative to the file path passed in `relative_to`
 
 `version_scheme : str | Callable[[ScmVersion], str]`
-: Configures how the local version number is constructed; either an entrypoint name or a callable.
+: Configures how the version number is constructed; either an entrypoint name or a callable.
+  See [Version number construction](extending.md#setuptools_scmversion_scheme) for predefined implementations.
 
 `local_scheme : str | Callable[[ScmVersion], str]`
-: Configures how the local component of the version is constructed
+: Configures how the local component of the version (the optional part after the `+`) is constructed;
   either an entrypoint name or a callable.
+  See [Version number construction](extending.md#setuptools_scmlocal_scheme) for predefined implementations.
 
 
 `version_file: Path | PathLike[str] | None = None`
@@ -69,14 +71,14 @@ Callables or other Python objects have to be passed in `setup.py` (via the `use_
 `fallback_version: str | None = None`
  :  A version string that will be used if no other method for detecting the
     version worked (e.g., when using a tarball with no metadata). If this is
-    unset (the default), `setuptools_scm` will error if it fails to detect the
+    unset (the default), `setuptools-scm` will error if it fails to detect the
     version.
 
 `parse: Callable[[Path, Config], ScmVersion] | None = None`
 :   A function that will be used instead of the discovered SCM
     for parsing the version. Use with caution,
     this is a function for advanced use and you should be
-    familiar with the `setuptools_scm` internals to use it.
+    familiar with the `setuptools-scm` internals to use it.
 
 `git_describe_command`
 :   This command will be used instead the default `git describe --long` command.
@@ -96,7 +98,7 @@ Callables or other Python objects have to be passed in `setup.py` (via the `use_
 
     The [setuptools_scm.NonNormalizedVersion][] convenience class is
     provided to disable the normalization step done by
-    `packaging.version.Version`. If this is used while `setuptools_scm`
+    `packaging.version.Version`. If this is used while `setuptools-scm`
     is integrated in a setuptools packaging process, the non-normalized
     version number will appear in all files (see `version_file` note).
 
@@ -121,7 +123,7 @@ Callables or other Python objects have to be passed in `setup.py` (via the `use_
     in which case it will be an unparsed string.
     Specifying distribution-specific pretend versions will
     avoid possible collisions with third party distributions
-    also using ``setuptools_scm``
+    also using ``setuptools-scm``
 
     the dist name normalization follows adapted PEP 503 semantics, with one or
     more of ".-\_" being replaced by a single "\_", and the name being upper-cased

docs/customizing.md

@@ -3,10 +3,10 @@
 ## providing project local version schemes
 
 As PEP 621 provides no way to specify local code as a build backend plugin,
-setuptools_scm has to piggyback on setuptools for passing functions over.
+setuptools-scm has to piggyback on setuptools for passing functions over.
 
 To facilitate that one needs to write a `setup.py` file and
-pass partial setuptools_scm configuration in via the use_scm_version keyword.
+pass partial setuptools-scm configuration in via the use_scm_version keyword.
 
 It's strongly recommended to experiment with using stock version schemes or creating plugins as package.
 (This recommendation will change if there ever is something like build-time entrypoints).
@@ -33,7 +33,7 @@ setup(use_scm_version={"version_scheme": myversion_func})
 
 ``` { .toml title="pyproject.toml" file="docs/examples/version_scheme_code/pyproject.toml" }
 [build-system]
-requires = ["setuptools>=64", "setuptools_scm>=8"]
+requires = ["setuptools>=64", "setuptools-scm>=8"]
 build-backend = "setuptools.build_meta"
 
 [project]
@@ -52,7 +52,7 @@ dynamic = [
 
 ##  Importing in setup.py
 
-With the pep 517/518 build backend, setuptools_scm is importable from `setup.py`
+With the pep 517/518 build backend, setuptools-scm is importable from `setup.py`
 
 ``` { .python title="setup.py" }
 import setuptools

docs/examples/version_scheme_code/pyproject.toml

@@ -1,6 +1,6 @@
 # ~/~ begin <<docs/customizing.md#docs/examples/version_scheme_code/pyproject.toml>>[init]
 [build-system]
-requires = ["setuptools>=64", "setuptools_scm>=8"]
+requires = ["setuptools>=64", "setuptools-scm>=8"]
 build-backend = "setuptools.build_meta"
 
 [project]
@@ -10,4 +10,4 @@ dynamic = [
 ]
 
 [tool.setuptools_scm]
-# ~/~ end
+# ~/~ end

docs/extending.md

@@ -1,12 +1,12 @@
-# Extending setuptools_scm
+# Extending setuptools-scm
 
-`setuptools_scm` uses [entry-point][entry-point] based hooks to extend its default capabilities.
+`setuptools-scm` uses [entry-point][entry-point] based hooks to extend its default capabilities.
 
 [entry-point]: https://packaging.python.org/en/latest/specifications/entry-points/
 
 ## Adding a new SCM
 
-`setuptools_scm` provides two entrypoints for adding new SCMs:
+`setuptools-scm` provides two entrypoints for adding new SCMs:
 
 `setuptools_scm.parse_scm`
 :   A function used to parse the metadata of the current workdir

docs/index.md

@@ -1,10 +1,10 @@
 # About
 
-`setuptools_scm` extracts Python package versions from `git` or `hg` metadata
+`setuptools-scm` extracts Python package versions from `git` or `hg` metadata
 instead of declaring them as the version argument
 or in a Source Code Managed (SCM) managed file.
 
-Additionally `setuptools_scm` provides `setuptools` with a list of
+Additionally `setuptools-scm` provides `setuptools` with a list of
 files that are managed by the SCM
 (i.e. it automatically adds all the SCM-managed files to the sdist).
 Unwanted files must be excluded via `MANIFEST.in`
@@ -16,13 +16,13 @@ or [configuring Git archive][git-archive-docs].
 
 ### With setuptools
 
-Note: `setuptools_scm>=8` intentionally doesn't depend on setuptools to ease non-setuptools usage.
+Note: `setuptools-scm>=8` intentionally doesn't depend on setuptools to ease non-setuptools usage.
 Please ensure a recent version of setuptools (>=64) is installed.
 
 
 ```toml title="pyproject.toml"
 [build-system]
-requires = ["setuptools>=64", "setuptools_scm>=8"]
+requires = ["setuptools>=64", "setuptools-scm>=8"]
 build-backend = "setuptools.build_meta"
 
 [project]
@@ -39,6 +39,6 @@ dynamic = ["version"]
 
 ### With hatch
 
-[Hatch-vcs](https://github.com/ofek/hatch-vcs) integrates with setuptools_scm
+[Hatch-vcs](https://github.com/ofek/hatch-vcs) integrates with setuptools-scm
 but provides its own configuration options,
 please see its [documentation](https://github.com/ofek/hatch-vcs#readme)

docs/overrides.md

@@ -2,7 +2,7 @@
 
 ## pretend versions
 
-setuptools_scm provides a mechanism to override the version number build time.
+setuptools-scm provides a mechanism to override the version number build time.
 
 the environment variable `SETUPTOOLS_SCM_PRETEND_VERSION` is used
 as the override source for the version number unparsed string.
@@ -12,7 +12,7 @@ where the dist name normalization follows adapted PEP 503 semantics.
 
 ## config overrides
 
-setuptools_scm parses the environment variable `SETUPTOOLS_SCM_OVERRIDES_FOR_${NORMALIZED_DIST_NAME}`
+setuptools-scm parses the environment variable `SETUPTOOLS_SCM_OVERRIDES_FOR_${NORMALIZED_DIST_NAME}`
 as a toml inline map to override the configuration data from `pyproject.toml`.
 
 ## subprocess timeouts

docs/usage.md

@@ -2,25 +2,25 @@
 
 ## At build time
 
-The preferred way to configure `setuptools_scm` is to author
+The preferred way to configure `setuptools-scm` is to author
 settings in the `tool.setuptools_scm` section of `pyproject.toml`.
 
 It's necessary to use a setuptools version released after 2022.
 
 ```toml title="pyproject.toml"
 [build-system]
-requires = ["setuptools>=64", "setuptools_scm>=8"]
+requires = ["setuptools>=64", "setuptools-scm>=8"]
 build-backend = "setuptools.build_meta"
 
 [project]
 # version = "0.0.1"  # Remove any existing version parameter.
 dynamic = ["version"]
 
 [tool.setuptools_scm]
-# can be empty if no extra settings are needed, presence enables setuptools_scm
+# can be empty if no extra settings are needed, presence enables setuptools-scm
 ```
 
-That will be sufficient to require `setuptools_scm` for projects
+That will be sufficient to require `setuptools-scm` for projects
 that support PEP 518 ([pip](https://pypi.org/project/pip) and
 [pep517](https://pypi.org/project/pep517/)).
 Tools that still invoke `setup.py` must ensure build requirements are installed
@@ -46,7 +46,7 @@ the runtime discussion below for more details.
 
 If you need to confirm which version string is being generated
 or debug the configuration, you can install
-[setuptools-scm](https://github.com/pypa/setuptools_scm)
+[setuptools-scm](https://github.com/pypa/setuptools-scm)
 directly in your working environment and run:
 
 ```commandline
@@ -79,7 +79,6 @@ To explore other options, try
 
 ```commandline
 $ python -m setuptools_scm --help
-```
 
 ## At runtime
 
@@ -192,7 +191,7 @@ is preferred over `SETUPTOOLS_SCM_PRETEND_VERSION`.
 
 ## Default versioning scheme
 
-In the standard configuration `setuptools_scm` takes a look at three things:
+In the standard configuration `setuptools-scm` takes a look at three things:
 
 1. latest tag (with a version number)
 2. the distance to this tag (e.g. number of revisions since latest tag)
@@ -281,14 +280,14 @@ $ git add .git_archival.txt .gitattributes && git commit -m "add export config"
 Note that if you are creating a `_version.py` file, note that it should not
 be kept in version control. It's strongly recommended to be put into gitignore.
 
-[git-archive-issue]: https://github.com/pypa/setuptools_scm/issues/806
+[git-archive-issue]: https://github.com/pypa/setuptools-scm/issues/806
 
 ### File finders hook makes most of `MANIFEST.in` unnecessary
 
-`setuptools_scm` implements a [file_finders] entry point
+`setuptools-scm` implements a [file_finders] entry point
 which returns all files tracked by your SCM.
 This eliminates the need for a manually constructed `MANIFEST.in` in most cases where this
-would be required when not using `setuptools_scm`, namely:
+would be required when not using `setuptools-scm`, namely:
 
 * To ensure all relevant files are packaged when running the `sdist` command.
   * When using [include_package_data] to include package data as part of the `build` or `bdist_wheel`.

pyproject.toml

@@ -4,7 +4,7 @@
 build-backend = "_own_version_helper:build_meta"
 requires = [
   "setuptools>=61",
-  'tomli; python_version < "3.11"',
+  'tomli<=2.0.2; python_version < "3.11"',
 ]
 backend-path = [
   ".",
@@ -41,7 +41,7 @@ dynamic = [
 ]
 dependencies = [
   "packaging>=20",
-  "setuptools",
+  "setuptools>=61",
   'tomli>=1; python_version < "3.11"',
   'typing-extensions; python_version < "3.10"',
 ]
@@ -68,7 +68,7 @@ toml = [
 ]
 [project.urls]
 documentation = "https://setuptools-scm.readthedocs.io/"
-repository = "https://github.com/pypa/setuptools_scm/"
+repository = "https://github.com/pypa/setuptools-scm/"
 [project.entry-points."distutils.setup_keywords"]
 use_scm_version = "setuptools_scm._integration.setuptools:version_keyword"
 [project.entry-points."pipx.run"]

src/setuptools_scm/_cli.py

@@ -61,7 +61,7 @@ def _get_cli_opts(args: list[str] | None) -> argparse.Namespace:
         "--config",
         default=None,
         metavar="PATH",
-        help="path to 'pyproject.toml' with setuptools_scm config, "
+        help="path to 'pyproject.toml' with setuptools-scm config, "
         "default: looked up in the current or parent directories",
     )
     parser.add_argument(
@@ -89,7 +89,7 @@ def _get_cli_opts(args: list[str] | None) -> argparse.Namespace:
         "--query",
         type=str.casefold,
         nargs="*",
-        help="display setuptools_scm settings according to query, "
+        help="display setuptools-scm settings according to query, "
         "e.g. dist_name, do not supply an argument in order to "
         "print a list of valid queries.",
     )

src/setuptools_scm/_get_version_impl.py

@@ -149,7 +149,7 @@ def get_version(
     """
     If supplied, relative_to should be a file from which root may
     be resolved. Typically called by a script or module that is not
-    in the root of the repository to direct setuptools_scm to the
+    in the root of the repository to direct setuptools-scm to the
     root of the repository by supplying ``__file__``.
     """
 

src/setuptools_scm/_integration/dump_version.py

@@ -13,11 +13,16 @@
 
 TEMPLATES = {
     ".py": """\
-# file generated by setuptools_scm
+# file generated by setuptools-scm
 # don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
 TYPE_CHECKING = False
 if TYPE_CHECKING:
-    from typing import Tuple, Union
+    from typing import Tuple
+    from typing import Union
+
     VERSION_TUPLE = Tuple[Union[int, str], ...]
 else:
     VERSION_TUPLE = object

src/setuptools_scm/_integration/setuptools.py

@@ -31,10 +31,10 @@ def _warn_on_old_setuptools(_version: str = setuptools.__version__) -> None:
         warnings.warn(
             RuntimeWarning(
                 f"""
-ERROR: setuptools=={_version} is used in combination with setuptools_scm>=8.x
+ERROR: setuptools=={_version} is used in combination with setuptools-scm>=8.x
 
 Your build configuration is incomplete and previously worked by accident!
-setuptools_scm requires setuptools>=61
+setuptools-scm requires setuptools>=61
 
 Suggested workaround if applicable:
  - migrating from the deprecated setup_requires mechanism to pep517/518
@@ -113,7 +113,7 @@ def infer_version(dist: setuptools.Distribution) -> None:
         dist_name = read_dist_name_from_setup_cfg()
     if not os.path.isfile("pyproject.toml"):
         return
-    if dist_name == "setuptools_scm":
+    if dist_name == "setuptools-scm":
         return
     try:
         config = _config.Configuration.from_file(dist_name=dist_name)