[ { "path": ".coveragerc", "content": "# https://pytest-cov.readthedocs.io/\n\n[run]\nsource = semver\nbranch = True\n\n[report]\nshow_missing = true\nprecision = 1\nexclude_lines =\n pragma: no cover\n if __name__ == .__main__.:\n if not hasattr\\(__builtins__, .cmp.\\):\n" }, { "path": ".editorconfig", "content": "# http://editorconfig.org\nroot = true\n\n[*]\nend_of_line = lf\ncharset = utf-8\nmax_line_length = 99\n\n[*.py]\nindent_style = space\nindent_size = 4\ntrim_trailing_whitespace = true\ninsert_final_newline = true\n\n[docs/Makefile]\nindent_style = tab\n" }, { "path": ".github/ISSUE_TEMPLATE/bug_report.yaml", "content": "name: 🐞Bug report\ndescription: Create a bug report to help us improve\n# title: ''\nlabels: [bug]\nassignees: [tomschr]\n\nbody:\n - type: markdown\n attributes:\n value: |\n Thanks a lot for taking the time to fill out this bug report! 🐛\n It will help us to improve the project for everyone. 🌟\n\n Find help from the community on our [GitHub Discussions](https://github.com/python-semver/python-semver/discussions) page or\n on our [Documentation](https://python-semver.readthedocs.io/en/latest/).\n\n - type: dropdown\n id: python_version\n attributes:\n label: Which version of Python is the problem with?\n multiple: true\n options:\n - \"3.7\"\n - \"3.8\"\n - \"3.9\"\n - \"3.10\"\n - \"3.11\"\n - \"3.12\"\n - \"3.13\"\n - \"3.14\"\n validations:\n required: true\n\n - type: input\n id: semver_version\n attributes:\n label: What semver version are you using?\n description: You can find this with `pip show semver`\n placeholder: 3.0.2\n\n - type: dropdown\n id: os\n attributes:\n label: What OS are you using? (Add more in the Environment section)\n multiple: true\n options:\n - Linux\n - Windows\n - macOS\n - Other\n\n - type: textarea\n id: situation\n attributes:\n label: Situation\n description: A clear and concise description of what the bug is.\n placeholder: Describe the problem you see...\n validations:\n required: true\n\n - type: textarea\n id: reproduction_steps\n attributes:\n label: How to reproduce\n description: |\n Steps to reproduce the behavior:\n 1. Run '...'\n 2. Scroll down to '....'\n 3. See error\n placeholder: Describe the steps to reproduce the issue...\n validations:\n required: true\n\n - type: textarea\n id: expected_behavior\n attributes:\n label: Expected behavior\n description: A clear and concise description of what you expected to happen.\n placeholder: Describe the expected behavior...\n validations:\n required: true\n\n - type: textarea\n id: environment\n attributes:\n label: Environment\n description: Optionally provide some more details about your environment.\n placeholder: Describe your environment...\n" }, { "path": ".github/ISSUE_TEMPLATE/config.yml", "content": "blank_issues_enabled: true\ncontact_links:\n - name: Community Support\n url: https://github.com/python-semver/python-semver/discussions\n about: Ask and answer questions in our discussion forum.\n - name: Documentation\n url: https://python-semver.readthedocs.io/\n about: Find more information in our documentation.\n" }, { "path": ".github/ISSUE_TEMPLATE/feature_request.yaml", "content": "name: Feature request\ndescription: Suggest an idea for this project\n# title: ''\nlabels: [enhancement]\nassignees: [tomschr]\n\nbody:\n - type: markdown\n attributes:\n value: |\n Thanks for taking the time to fill out this feature request!\n\n - type: textarea\n id: situation\n attributes:\n label: Situation\n description: A clear and concise description of what the feature is. Ex. I'm always frustrated when [...]\n placeholder: Describe the situation...\n validations:\n required: true\n\n - type: textarea\n id: expected_solution\n attributes:\n label: Expected solution\n description: A clear and concise description of what you want to happen.\n placeholder: Describe the expected solution...\n validations:\n required: true\n\n - type: textarea\n id: alternatives\n attributes:\n label: Alternatives\n description: A clear and concise description of any alternative solutions or features you've considered.\n placeholder: Describe any alternatives..." }, { "path": ".github/dependabot.yml", "content": "# To get started with Dependabot version updates, you'll need to specify which\n# package ecosystems to update and where the package manifests are located.\n# Please see the documentation for all configuration options:\n# https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates\n\nversion: 2\nupdates:\n - package-ecosystem: \"pip\" # See documentation for possible values\n directory: \"/\" # Location of package manifests\n schedule:\n interval: \"weekly\"\n day: \"friday\"\n labels:\n - \"enhancement\"\n commit-message:\n prefix: \"pip\"\n # Allow up to 10 open pull requests for pip dependencies\n open-pull-requests-limit: 5\n" }, { "path": ".github/workflows/codeql-analysis.yml", "content": "# For most projects, this workflow file will not need changing; you simply need\n# to commit it to your repository.\n#\n# You may wish to alter this file to override the set of languages analyzed,\n# or to provide custom queries or build logic.\n#\n# ******** NOTE ********\n# We have attempted to detect the languages in your repository. Please check\n# the `language` matrix defined below to confirm you have the correct set of\n# supported CodeQL languages.\n#\nname: \"CodeQL\"\n\non:\n push:\n branches: [ maint/v2, release/* ]\n pull_request:\n # The branches below must be a subset of the branches above\n branches: [ master ]\n schedule:\n - cron: '50 16 * * 5'\n\njobs:\n analyze:\n name: Analyze\n runs-on: ubuntu-latest\n\n strategy:\n fail-fast: false\n matrix:\n language: [ 'python' ]\n # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python' ]\n # Learn more:\n # https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#changing-the-languages-that-are-analyzed\n\n steps:\n - name: Checkout repository\n uses: actions/checkout@v4\n\n # Initializes the CodeQL tools for scanning.\n - name: Initialize CodeQL\n uses: github/codeql-action/init@v3\n with:\n languages: ${{ matrix.language }}\n # If you wish to specify custom queries, you can do so here or in a config file.\n # By default, queries listed here will override any specified in a config file.\n # Prefix the list here with \"+\" to use these queries and those in the config file.\n # queries: ./path/to/local/query, your-org/your-repo/queries@main\n\n # Autobuild attempts to build any compiled languages (C/C++, C#, or Java).\n # If this step fails, then you should remove it and run the build manually (see below)\n - name: Autobuild\n uses: github/codeql-action/autobuild@v3\n\n # ℹ️ Command-line programs to run using the OS shell.\n # 📚 https://git.io/JvXDl\n\n # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines\n # and modify them (or add more) to build your code if your project\n # uses a compiled language\n\n #- run: |\n # make bootstrap\n # make release\n\n - name: Perform CodeQL Analysis\n uses: github/codeql-action/analyze@v3\n" }, { "path": ".github/workflows/python-testing.yml", "content": "---\nname: Python\n\n# HINT: Sync this paths with the egrep in step check_files\non:\n push:\n branches: [ \"master\", \"main\" ]\n paths:\n - 'pyproject.toml'\n - 'setup.cfg'\n - '**.py'\n - '.github/workflows/*.yml'\n\n pull_request:\n branches: [ \"master\", \"main\" ]\n paths:\n - 'pyproject.toml'\n - 'setup.cfg'\n - '**.py'\n - '.github/workflows/*.yml'\n\npermissions:\n contents: read\n\nconcurrency:\n # only cancel in-progress runs of the same workflow\n group: ${{ github.workflow }}-${{ github.ref }}\n cancel-in-progress: true\n\n\njobs:\n check-files:\n runs-on: ubuntu-latest\n outputs:\n can_run: ${{ steps.check_files.outputs.can_run }}\n\n steps:\n - uses: actions/checkout@v4\n with:\n fetch-depth: 0\n\n - name: GitHub variables\n id: gh-vars\n run: |\n for var in GITHUB_WORKFLOW GITHUB_ACTION GITHUB_ACTIONS GITHUB_REPOSITORY GITHUB_EVEN_NAME GITHUB_EVENT_PATH GITHUB_WORKSPACE GITHUB_SHA GITHUB_REF GITHUB_HEAD_REF GITHUB_BASE_REF; do\n echo \"$var = ${!var}\"\n done\n\n - name: Check for file changes\n id: check_files\n run: |\n # ${{ github.event.after }} ${{ github.event.before }}\n can_run=$(git diff --name-only HEAD~1 HEAD | \\\n egrep -q '.github/workflows/|pyproject.toml|setup.cfg|\\.py$' && echo 1 || echo 0)\n echo \"can_run=$can_run\"\n echo \"can_run=$can_run\" >> $GITHUB_OUTPUT\n\n skip_test:\n runs-on: ubuntu-latest\n needs: check-files\n timeout-minutes: 2\n if: ${{ needs.check-files.outputs.can_run == '0' }}\n\n steps:\n - name: Skip test\n run: |\n echo \"Nothing to do as no TOML, Python, or YAML file has been changed.\n \"\n echo \"Skipping.\"\n\n check:\n runs-on: ubuntu-latest\n needs: check-files\n timeout-minutes: 15\n # needs.check-files.outputs.can_run\n if: ${{ needs.check-files.outputs.can_run == '1' }}\n\n steps:\n - uses: actions/checkout@v4\n\n - name: Install uv\n uses: astral-sh/setup-uv@v3\n with:\n enable-cache: true\n\n - name: Set up Python 3.7\n # check tox.ini for the lowest version\n run: uv python install 3.7\n\n - name: Install the project\n run: |\n uv sync --all-extras --group gh-action\n\n - name: Checks\n continue-on-error: true\n run: uv run tox run -e checks\n\n tests:\n needs: check\n runs-on: ${{ matrix.os }}\n # continue-on-error: true\n strategy:\n max-parallel: 5\n fail-fast: true\n matrix:\n python-version: [\"3.7\",\n \"3.8\",\n \"3.9\",\n \"3.10\",\n \"3.11\",\n \"3.12\",\n \"3.13\",\n ]\n os: [\"ubuntu-latest\", \"macos-latest\"]\n exclude:\n - os: \"macos-latest\"\n python-version: \"3.7\"\n\n steps:\n - uses: actions/checkout@v4\n\n - name: Install uv\n uses: astral-sh/setup-uv@v3\n\n - name: Set up Python ${{ matrix.python-version }}\n run: uv python install ${{ matrix.python-version }}\n\n - name: Install the project\n run: |\n uv sync --all-extras --dev\n uv pip install tox tox-gh-actions\n\n - name: Checks\n run: uv run tox run -e ${{ matrix.python-version }}\n" }, { "path": ".gitignore", "content": "# Python .gitignore file from gh://github/gitignore/Python.gitignore\n#\n# Byte-compiled / optimized / DLL files\n__pycache__/\n*.py[cod]\n*$py.class\n\n# C extensions\n*.so\n\n# Distribution / packaging\n.Python\nbuild/\ndevelop-eggs/\ndist/\ndownloads/\neggs/\n.eggs/\nlib/\nlib64/\nparts/\nsdist/\nvar/\nwheels/\nshare/python-wheels/\n*.egg-info/\n.installed.cfg\n*.egg\nMANIFEST\n\n# PyInstaller\n# Usually these files are written by a python script from a template\n# before PyInstaller builds the exe, so as to inject date/other infos into it.\n*.manifest\n*.spec\n\n# Installer logs\npip-log.txt\npip-delete-this-directory.txt\n\n# Unit test / coverage reports\nhtmlcov/\n.tox/\n.nox/\n.coverage\n.coverage.*\n.cache\nnosetests.xml\ncoverage.xml\n*.cover\n*.py,cover\n.hypothesis/\n.pytest_cache/\ncover/\n\n# Translations\n*.mo\n*.pot\n\n# Django stuff:\n*.log\nlocal_settings.py\ndb.sqlite3\ndb.sqlite3-journal\n\n# Flask stuff:\ninstance/\n.webassets-cache\n\n# Scrapy stuff:\n.scrapy\n\n# Sphinx documentation\ndocs/_build/\n\n# PyBuilder\n.pybuilder/\ntarget/\n\n# Jupyter Notebook\n.ipynb_checkpoints\n\n# IPython\nprofile_default/\nipython_config.py\n\n# pyenv\n# For a library or package, you might want to ignore these files since the code is\n# intended to run in multiple environments; otherwise, check them in:\n.python-version\n\n# pipenv\n# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.\n# However, in case of collaboration, if having platform-specific dependencies or dependencies\n# having no cross-platform support, pipenv may install dependencies that don't work, or not\n# install all needed dependencies.\n#Pipfile.lock\n\n# PEP 582; used by e.g. github.com/David-OConnor/pyflow\n__pypackages__/\n\n# Celery stuff\ncelerybeat-schedule\ncelerybeat.pid\n\n# SageMath parsed files\n*.sage.py\n\n# Environments\n.env\n.venv*\nenv/\nvenv/\nENV/\nenv.bak/\nvenv.bak/\n\n# Spyder project settings\n.spyderproject\n.spyproject\n\n# Rope project settings\n.ropeproject\n\n# mkdocs documentation\n/site\n\n# mypy\n.mypy_cache/\n.dmypy.json\ndmypy.json\n\n# Pyre type checker\n.pyre/\n\n# pytype static type analyzer\n.pytype/\n\n# Cython debug symbols\ncython_debug/\n\n#/-- Python\n\n#--- Kate from gh://github/gitignore/Global/Kate.gitignore\n*.kate-swp\n.swp.*\n#/--- Kate\n\n#--- Vim from gh://github/gitignore/Global/Vim.gitignore\n# Swap\n[._]*.s[a-v][a-z]\n!*.svg # comment out if you don't need vector files\n[._]*.sw[a-p]\n[._]s[a-rt-v][a-z]\n[._]ss[a-gi-z]\n[._]sw[a-p]\n\n# Session\nSession.vim\nSessionx.vim\n\n# Temporary\n.netrwhist\n*~\n# Auto-generated tag files\ntags\n# Persistent undo\n[._]*.un~\n#/--- Vim\n\n#--- VisualStudioCode from gh://github/gitignore/Global/VisualStudioCode.gitignore\n.vscode/*\n!.vscode/settings.json\n!.vscode/tasks.json\n!.vscode/launch.json\n!.vscode/extensions.json\n*.code-workspace\n\n# Local History for Visual Studio Code\n.history/\n\n#/--- VisualStudio\n\n#--- JetBrains from gh://github/gitignore/Global/JetBrains.gitignore\n# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider\n# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839\n\n# User-specific stuff\n.idea/**/workspace.xml\n.idea/**/tasks.xml\n.idea/**/usage.statistics.xml\n.idea/**/dictionaries\n.idea/**/shelf\n\n# Generated files\n.idea/**/contentModel.xml\n\n# Sensitive or high-churn files\n.idea/**/dataSources/\n.idea/**/dataSources.ids\n.idea/**/dataSources.local.xml\n.idea/**/sqlDataSources.xml\n.idea/**/dynamic.xml\n.idea/**/uiDesigner.xml\n.idea/**/dbnavigator.xml\n\n# Gradle\n.idea/**/gradle.xml\n.idea/**/libraries\n\n# Gradle and Maven with auto-import\n# When using Gradle or Maven with auto-import, you should exclude module files,\n# since they will be recreated, and may cause churn. Uncomment if using\n# auto-import.\n# .idea/artifacts\n# .idea/compiler.xml\n# .idea/jarRepositories.xml\n# .idea/modules.xml\n# .idea/*.iml\n# .idea/modules\n# *.iml\n# *.ipr\n\n# CMake\ncmake-build-*/\n\n# Mongo Explorer plugin\n.idea/**/mongoSettings.xml\n\n# File-based project format\n*.iws\n\n# IntelliJ\nout/\n\n# mpeltonen/sbt-idea plugin\n.idea_modules/\n\n# JIRA plugin\natlassian-ide-plugin.xml\n\n# Cursive Clojure plugin\n.idea/replstate.xml\n\n# Crashlytics plugin (for Android Studio and IntelliJ)\ncom_crashlytics_export_strings.xml\ncrashlytics.properties\ncrashlytics-build.properties\nfabric.properties\n\n# Editor-based Rest Client\n.idea/httpRequests\n\n# Android studio 3.1+ serialized cache file\n.idea/caches/build_file_checksums.ser\n\n#/--- JetBrains\n\n# --------\n\n\n# Ignore files in the project's root:\n/*.patch\n/*.diff\n/*.py\n# but not this file:\n!/setup.py\n\ndocs/_api\n!docs/_api/semver.__about__.rst\n\n# For node\nnode_modules/\n" }, { "path": ".pytest.ini", "content": "[pytest]\nnorecursedirs = .git build .env/ env/ .pyenv/ .tmp/ .eggs/ venv/\ntestpaths = tests docs\npythonpath = src tests\nfilterwarnings =\n ignore:Function 'semver.*:DeprecationWarning\n # ' <- This apostroph is just to fix syntax highlighting\naddopts =\n --import-mode=importlib\n --no-cov-on-fail\n --cov=semver\n --cov-report=term-missing\n --doctest-glob='*.rst'\n --doctest-modules\n --doctest-report ndiff" }, { "path": ".readthedocs.yaml", "content": "# .readthedocs.yaml\n# Read the Docs configuration file\n# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details\n\n# Required\nversion: 2\n\n# Set the version of Python and other tools you might need\nbuild:\n os: ubuntu-22.04\n tools:\n python: \"3.11\"\n jobs:\n pre_install:\n # - curl -LsSf https://astral.sh/uv/install.sh | sh\n - pip install uv\n - uv export --only-group docs --no-hashes --no-color > requirements-docs.txt\n post_install:\n - pip install -r requirements-docs.txt\n pre_build:\n - make -C docs html\n\n# Build documentation in the docs/ directory with Sphinx\nsphinx:\n configuration: docs/conf.py\n\n" }, { "path": ".ruff.toml", "content": "#\n# Configuration file for ruff\n# See https://docs.astral.sh/ruff/configuration/\n\nline-length = 88\nindent-width = 4\ninclude = [\n \"pyproject.toml\",\n \"src/**/*.py\",\n \"tests/**/*.py\",\n \"docs/**/*.py\",\n]\n\n[lint]\nextend-ignore = [\n \"RUF005\",\n \"RUF012\",\n # Comment contains ambiguous `’` (RIGHT SINGLE QUOTATION MARK):\n \"RUF003\",\n \"ISC001\",\n]\nselect = [\n \"F\", # pyflakes\n \"E\", # pycodestyle\n \"I\", # isort\n \"N\", # pep8-naming\n \"UP\", # pyupgrade\n \"RUF\", # ruff\n \"B\", # flake8-bugbear\n \"C4\", # flake8-comprehensions\n \"ISC\", # flake8-implicit-str-concat\n \"PTH\", # flake8-use-pathlib\n \"SIM\", # flake8-simplify\n \"TID\", # flake8-tidy-imports\n]\n# TODO: Remove ISC001 ignore when formatter updated: https://github.com/astral-sh/ruff/issues/8272\n\n\n[format]\n# Exclude type hint stub files from formatting.\nexclude = [\"*.pyi\"]\n\n# Like Black, use double quotes for strings.\nquote-style = \"double\"\n\n# Like Black, indent with spaces, rather than tabs.\nindent-style = \"space\"\n\n# Like Black, respect magic trailing commas.\nskip-magic-trailing-comma = false\n\ndocstring-code-format = true\ndocstring-code-line-length = \"dynamic\"" }, { "path": "CHANGELOG.rst", "content": "##########\nChange Log\n##########\n\nChanges for the upcoming release can be found in\nthe `\"changelog.d\" directory `_\nin our repository.\n\nThis section covers the changes between major version 2 and version 3.\n\n..\n Do *NOT* add changelog entries here!\n\n This changelog is managed by towncrier and is compiled at release time.\n\n See https://python-semver.rtd.io/en/latest/development.html#changelog\n for details.\n\n.. towncrier release notes start\n\nVersion 3.0.4\n=============\n\n:Released: 2025-01-24\n:Maintainer: Tom Schraitle\n\n\nBug Fixes\n---------\n\n* :gh:`459`: Fix 3.0.3:\n\n * :pr:`457`: Re-enable Trove license identifier\n * :pr:`456`: Fix source dist file\n\n\n----\n\n\nVersion 3.0.3\n=============\n\n:Released: 2025-01-18\n:Maintainer: Tom Schraitle\n\n\nBug Fixes\n---------\n\n* :pr:`453`: The check in ``_comparator`` does not match the check in :meth:`Version.compare`. \n This breaks comparision with subclasses.\n\n\n\nImproved Documentation\n----------------------\n\n* :pr:`435`: Several small improvements for documentation:\n\n * Add meta description to improve SEO\n * Use canonicals on ReadTheDocs (commit 87f639f)\n * Pin versions for reproducable doc builds (commit 03fb990)\n * Add missing :file:`.readthedocs.yaml` file (commit ec9348a)\n * Correct some smaller issues when building (commit f65feab)\n\n* :pr:`436`: Move search box more at the top. This makes it easier for\n users as if the TOC is long, the search box isn't visible\n anymore.\n\n\n\nFeatures\n--------\n\n* :pr:`439`: Improve type hints to fix TODOs\n\n\n\nInternal Changes\n----------------\n\n* :pr:`440`: Update workflow file\n\n* :pr:`446`: Add Python 3.13 to GitHub Actions\n\n* :pr:`447`: Modernize project configs with :file:`pyproject.toml` and\n use Astral's uv command.\n\n * In :file:`pyproject.toml`:\n\n * Move all project related data from :file:`setup.cfg` to :file:`pyproject.toml`\n * Use new dependency group from :pep:`735`\n * Consolidate flake8, isort, pycodestyle with ruff\n * Split towncrier config type \"trivial\" into \"trivial\" and \"internal\"\n\n * Create config file for ruff (:file:`.ruff.toml`)\n * Create config file for pytest (:file:`.pytest.ini`)\n * Simplify :file:`tox.ini` and remove old stuff\n * Document installation with new :command:`uv` command\n * Simplify Sphinx config with :func:`find_version()`\n * Update the authors\n * Use :command:`uv` in GitHub Action :file:`python-testing.yml` workflow\n\n* Update :file:`release-procedure.md`.\n\n* :pr:`451`: Turn our Markdown issue templates into YAML\n\n\nTrivial Changes\n---------------\n\n* :pr:`438`: Replace organization placeholder in license\n\n* :pr:`445`: Improve private :func:`_nat_cmp` method:\n\n * Remove obsolete else.\n * Find a better way to identify digits without the :mod:`re` module.\n * Fix docstring in :meth:`Version.compare`\n\n\n\n----\n\n\nVersion 3.0.2\n=============\n\n:Released: 2023-10-09\n:Maintainer: Tom Schraitle\n\n\nBug Fixes\n---------\n\n* :pr:`418`: Replace :class:`~collection.OrderedDict` with :class:`dict`.\n\n The dict datatype is ordered since Python 3.7. As we do not support\n Python 3.6 anymore, it can be considered safe to avoid :class:`~collection.OrderedDict`.\n Related to :gh:`419`.\n\n* :pr:`426`: Fix :meth:`~semver.version.Version.replace` method to use the derived class\n of an instance instead of :class:`~semver.version.Version` class.\n\n\n\nImproved Documentation\n----------------------\n\n* :pr:`431`: Clarify version policy for the different semver versions (v2, v3, >v3)\n and the supported Python versions.\n\n* :gh:`432`: Improve external doc links to Python and Pydantic.\n\n\n\nFeatures\n--------\n\n* :pr:`417`: Amend GitHub Actions to check against MacOS.\n\n\n\nTrivial/Internal Changes\n------------------------\n\n* :pr:`420`: Introduce :py:class:`~typing.ClassVar` for some :class:`~semver.version.Version`\n class variables, mainly :data:`~semver.version.Version.NAMES` and some private.\n\n* :pr:`421`: Insert mypy configuration into :file:`pyproject.toml` and remove\n config options from :file:`tox.ini`.\n\n\n\n----\n\n\nVersion 3.0.1\n=============\n\n:Released: 2023-06-14\n:Maintainer: Tom Schraitle\n\n\nBug Fixes\n---------\n\n* :gh:`410`: Export functions properly using ``__all__`` in ``__init__.py``.\n\n\n\n----\n\n\nVersion 3.0.0\n=============\n\n:Released: 2023-04-02\n:Maintainer: Tom Schraitle\n\n\nBug Fixes\n---------\n\n* :gh:`291`: Disallow negative numbers in VersionInfo arguments\n for ``major``, ``minor``, and ``patch``.\n\n* :gh:`310`: Rework API documentation.\n Follow a more \"semi-manual\" attempt and add auto directives\n into :file:`docs/api.rst`.\n\n* :gh:`344`: Allow empty string, a string with a prefix, or ``None``\n as token in\n :meth:`~semver.version.Version.bump_build` and\n :meth:`~semver.version.Version.bump_prerelease`.\n\n* :gh:`374`: Correct Towncrier's config entries in the :file:`pyproject.toml` file.\n The old entries ``[[tool.towncrier.type]]`` are deprecated and need\n to be replaced by ``[tool.towncrier.fragment.]``.\n\n* :pr:`384`: General cleanup, reformat files:\n\n * Reformat source code with black again as some config options\n did accidentely exclude the semver source code.\n Mostly remove some includes/excludes in the black config.\n * Integrate concurrency in GH Action\n * Ignore Python files on project dirs in .gitignore\n * Remove unused patterns in MANIFEST.in\n * Use ``extend-exclude`` for flake in :file:`setup.cfg`` and adapt list.\n * Use ``skip_install=True`` in :file:`tox.ini` for black\n\n* :pr:`393`: Fix command :command:`python -m semver` to avoid the error \"invalid choice\"\n\n* :pr:`396`: Calling :meth:`~semver.version.Version.parse` on a derived class will show correct type of derived class.\n\n\nDeprecations\n------------\n\n* :gh:`169`: Deprecate CLI functions not imported from ``semver.cli``.\n\n* :gh:`234`: In :file:`setup.py` simplified file and remove\n ``Tox`` and ``Clean`` classes\n\n* :gh:`284`: Deprecate the use of :meth:`~Version.isvalid`.\n\n Rename :meth:`~semver.version.Version.isvalid`\n to :meth:`~semver.version.Version.is_valid`\n for consistency reasons with :meth:`~semver.version.Version.is_compatible`.\n\n\n* :pr:`290`: For semver 3.0.0-alpha0 deprecated:\n\n * Remove anything related to Python2\n * In :file:`tox.ini` and :file:`.travis.yml`\n Remove targets py27, py34, py35, and pypy.\n Add py38, py39, and nightly (allow to fail)\n * In :file:`setup.py` simplified file and remove\n ``Tox`` and ``Clean`` classes\n * Remove old Python versions (2.7, 3.4, 3.5, and pypy)\n from Travis\n\n* :gh:`372`: Deprecate support for Python 3.6.\n\n Python 3.6 reached its end of life and isn't supported anymore.\n At the time of writing (Dec 2022), the lowest version is 3.7.\n\n Although the `poll `_\n didn't cast many votes, the majority agreed to remove support for\n Python 3.6.\n\n* :pr:`402`: Keep :func:`semver.compare `.\n Although it breaks consistency with module level functions, it seems it's\n a much needed/used function. It's still unclear if we should deprecate\n this function or not (that's why we use :py:exc:`PendingDeprecationWarning`).\n\n As we don't have a uniform initializer yet, this function stays in the\n :file:`_deprecated.py` file for the time being until we find a better solution. See :gh:`258` for details.\n\n\nFeatures\n--------\n\n* :gh:`169`: Create semver package and split code among different modules in the packages:\n\n * Remove :file:`semver.py`\n * Create :file:`src/semver/__init__.py`\n * Create :file:`src/semver/cli.py` for all CLI methods\n * Create :file:`src/semver/_deprecated.py` for the ``deprecated`` decorator and other deprecated functions\n * Create :file:`src/semver/__main__.py` to allow calling the CLI using :command:`python -m semver`\n * Create :file:`src/semver/_types.py` to hold type aliases\n * Create :file:`src/semver/version.py` to hold the :class:`Version` class (old name :class:`VersionInfo`) and its utility functions\n * Create :file:`src/semver/__about__.py` for all the metadata variables\n\n* :gh:`213`: Add typing information\n\n* :gh:`284`: Implement :meth:`~semver.version.Version.is_compatible` to make \"is self compatible with X\".\n\n* :gh:`305`: Rename :class:`~semver.version.VersionInfo` to :class:`~semver.version.Version` but keep an alias for compatibility\n\n* :pr:`359`: Add optional parameter ``optional_minor_and_patch`` in :meth:`~semver.version.Version.parse` to allow optional\n minor and patch parts.\n\n* :pr:`362`: Make :meth:`~semver.version.Version.match` accept a bare version string as match expression, defaulting to equality testing.\n\n* :gh:`364`: Enhance :file:`pyproject.toml` to make it possible to use the\n :command:`pyproject-build` command from the build module.\n For more information, see :ref:`build-semver`.\n\n* :gh:`365`: Improve :file:`pyproject.toml`.\n\n * Use setuptools, add metadata. Taken approach from\n `A Practical Guide to Setuptools and Pyproject.toml\n `_.\n * Doc: Describe building of semver\n * Remove :file:`.travis.yml` in :file:`MANIFEST.in`\n (not needed anymore)\n * Distinguish between Python 3.6 and others in :file:`tox.ini`\n * Add skip_missing_interpreters option for :file:`tox.ini`\n * GH Action: Upgrade setuptools and setuptools-scm and test\n against 3.11.0-rc.2\n\n\n\nImproved Documentation\n----------------------\n\n* :gh:`276`: Document how to create a sublass from :class:`~semver.version.VersionInfo` class\n\n* :gh:`284`: Document deprecation of :meth:`~semver.version.Version.isvalid`.\n\n* :pr:`290`: Several improvements in the documentation:\n\n * New layout to distinguish from the semver2 development line.\n * Create new logo.\n * Remove any occurances of Python2.\n * Describe changelog process with Towncrier.\n * Update the release process.\n\n* :gh:`304`: Several improvements in documentation:\n\n * Reorganize API documentation.\n * Add migration chapter from semver2 to semver3.\n * Distinguish between changlog for version 2 and 3\n\n* :gh:`305`: Add note about :class:`~semver.version.Version` rename.\n\n* :gh:`312`: Rework \"Usage\" section.\n\n * Mention the rename of :class:`~semver.version.VersionInfo` to\n :class:`~semver.version.Version` class\n * Remove semver. prefix in doctests to make examples shorter\n * Correct some references to dunder methods like\n :func:`~semver.version.Version.__getitem__`,\n :func:`~semver.version.Version.__gt__` etc.\n * Remove inconsistencies and mention module level function as\n deprecated and discouraged from using\n * Make empty :py:func:`super` call in :file:`semverwithvprefix.py` example\n\n* :gh:`315`: Improve release procedure text\n\n* :gh:`335`: Add new section \"Converting versions between PyPI and semver\" the limitations\n and possible use cases to convert from one into the other versioning scheme.\n\n* :gh:`340`: Describe how to get version from a file\n\n* :gh:`343`: Describe combining Pydantic with semver in the \"Advanced topic\"\n section.\n\n* :gh:`350`: Restructure usage section. Create subdirectory \"usage/\" and splitted\n all section into different files.\n\n* :gh:`351`: Introduce new topics for:\n\n * \"Migration to semver3\"\n * \"Advanced topics\"\n\n* :pr:`392`: Fix the example in the documentation for combining semver and pydantic.\n\n\nTrivial/Internal Changes\n------------------------\n\n* :gh:`169`: Adapted infrastructure code to the new project layout.\n\n * Replace :file:`setup.py` with :file:`setup.cfg` because the :file:`setup.cfg` is easier to use\n * Adapt documentation code snippets where needed\n * Adapt tests\n * Changed the ``deprecated`` to hardcode the ``semver`` package name in the warning.\n\n Increase coverage to 100% for all non-deprecated APIs\n\n* :pr:`290`: Add supported Python versions to :command:`black`.\n\n* :gh:`304`: Support PEP-561 :file:`py.typed`.\n\n According to the mentioned PEP:\n\n \"Package maintainers who wish to support type checking\n of their code MUST add a marker file named :file:`py.typed`\n to their package supporting typing.\"\n\n Add package_data to :file:`setup.cfg` to include this marker in dist\n and whl file.\n\n* :gh:`309`: Some (private) functions from the :mod:`semver.version`\n module has been changed.\n\n The following functions got renamed:\n\n * function :func:`semver.version.comparator` got renamed to\n :func:`semver.version._comparator` as it is only useful\n inside the :class:`~semver.version.Version` class.\n * function :func:`semver.version.cmp` got renamed to\n :func:`semver.version._cmp` as it is only useful\n inside the :class:`~semver.version.Version` class.\n\n The following functions got integrated into the\n :class:`~semver.version.Version` class:\n\n * function :func:`semver.version._nat_cmd` as a classmethod\n * function :func:`semver.version.ensure_str`\n\n* :gh:`313`: Correct :file:`tox.ini` for ``changelog`` entry to skip\n installation for semver. This should speed up the execution\n of towncrier.\n\n* :gh:`316`: Comparisons of :class:`~semver.version.Version` class and other\n types return now a :py:const:`NotImplemented` constant instead\n of a :py:exc:`TypeError` exception.\n\n The `NotImplemented`_ section of the Python documentation recommends\n returning this constant when comparing with ``__gt__``, ``__lt__``,\n and other comparison operators to \"to indicate that the operation is\n not implemented with respect to the other type\".\n\n .. _NotImplemented: https://docs.python.org/3/library/constants.html#NotImplemented\n\n* :gh:`319`: Introduce stages in :file:`.travis.yml`\n The config file contains now two stages: check and test. If\n check fails, the test stage won't be executed. This could\n speed up things when some checks fails.\n\n* :gh:`322`: Switch from Travis CI to GitHub Actions.\n\n* :gh:`347`: Support Python 3.10 in GitHub Action and other config files.\n\n* :gh:`378`: Fix some typos in Towncrier configuration\n\n* :gh:`388`: For pytest, switch to the more modern :mod:`importlib` approach\n as it doesn't require to modify :data:`sys.path`:\n https://docs.pytest.org/en/7.2.x/explanation/pythonpath.html\n\n* :pr:`389`: Add public class variable :data:`Version.NAMES `.\n\n This class variable contains a tuple of strings that contains the names of\n all attributes of a Version (like ``\"major\"``, ``\"minor\"`` etc).\n\n In cases we need to have dynamical values, this makes it easier to iterate.\n\n\n\n..\n Local variables:\n coding: utf-8\n mode: text\n mode: rst\n End:\n vim: fileencoding=utf-8 filetype=rst :\n" }, { "path": "CITATION.cff", "content": "# This CITATION.cff file was generated with cffinit:\n# https://bit.ly/cffinit\n\ncff-version: 1.2.0\ntitle: python-semver\nmessage: >-\n If you use this software, please cite it using the\n metadata from this file.\ntype: software\n\nauthors:\n - given-names: Kostiantyn\n family-names: Rybnikov\n email: k-bx@k-bx.com\n - given-names: Tom\n family-names: Schraitle\n email: tom_schr@web.de\n - given-names: Sebastian\n family-names: Celles\n email: s.celles@gmail.com\n - name: \"The python-semver software team\"\n\nidentifiers:\n - type: url\n value: 'https://github.com/python-semver/python-semver'\n description: GitHub python-semver/python-semver\nurl: 'https://python-semver.readthedocs.io'\nrepository-code: 'https://github.com/python-semver/python-semver'\nrepository-artifact: 'https://pypi.org/project/semver/'\n\nabstract: >-\n A Python module for semantic versioning. Simplifies\n comparing versions. This modules follows the\n MAJOR.MINOR.PATCH style.\n\nkeywords:\n - Python\n - Python module\n - semver\n - versioning\n - semantic versioning\n - semver-format\n - semver-tag\n - versions\n\nreferences:\n - authors:\n - family-names: Preston-Werner\n given-names: Tom\n - name: \"The semver team\"\n title: 'Semantic Versioning 2.0.0'\n url: 'https://semver.org'\n repository-code: 'https://github.com/semver/semver'\n type: standard\n version: 2.0.0\n languages:\n - ar\n - bg\n - ca\n - cs\n - da\n - de\n - el\n - en\n - es\n - fa\n - fr\n - he\n - hin\n - hr\n - hu\n - hy\n - id\n - it\n - ja\n - ka\n - kab\n - ko\n - nl\n - pl\n - pt\n - ro\n - ru\n - sk\n - sl\n - sr\n - sv\n - tr\n - uk\n - vi\n - zh\n abstract: >-\n Given a version number MAJOR.MINOR.PATCH, increment the:\n\n 1. MAJOR version when you make incompatible API changes\n 2. MINOR version when you add functionality in a backwards compatible manner\n 3. PATCH version when you make backwards compatible bug fixes\n\n Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.\n\nlicense: BSD-3-Clause\ncommit: 3a7680dc436211227c0aeae84c9b45e0b3345b8f\nversion: 3.0.0\ndate-released: '2023-04-02'\n" }, { "path": "CONTRIBUTING.rst", "content": ".. _contributing:\n\nContributing to semver\n======================\n\nThe semver source code is managed using Git and is hosted on GitHub::\n\n git clone git://github.com/python-semver/python-semver\n\n\n\nReporting Bugs and Asking Questions\n-----------------------------------\n\nIf you think you have encountered a bug in semver or have an idea for a new\nfeature? Great! We like to hear from you!\n\nThere are several options to participate:\n\n* Open a new topic on our `GitHub discussion `_ page.\n Tell us our ideas or ask your questions.\n\n* Look into our GitHub `issues`_ tracker or open a new issue.\n\n\nPrerequisites\n-------------\n\nBefore you make changes to the code, we would highly appreciate if you\nconsider the following general requirements:\n\n* Make sure your code adheres to the `Semantic Versioning`_ specification.\n\n* Check if your feature is covered by the Semantic Versioning specification.\n If not, ask on its GitHub project https://github.com/semver/semver.\n\n\nMore topics\n-----------\n\n* `Running the Test Suite `_\n* `Documenting semver `_\n* `Adding a Changelog Entry `_\n* `Preparing the Release `_\n* `Finish the Release `_\n\n\n.. _black: https://black.rtfd.io\n.. _docformatter: https://pypi.org/project/docformatter/\n.. _flake8: https://flake8.rtfd.io\n.. _mypy: http://mypy-lang.org/\n.. _issues: https://github.com/python-semver/python-semver/issues\n.. _pull request: https://github.com/python-semver/python-semver/pulls\n.. _pytest: http://pytest.org/\n.. _Semantic Versioning: https://semver.org\n.. _Sphinx style: https://sphinx-rtd-tutorial.rtfd.io/en/latest/docstrings.html\n.. _tox: https://tox.rtfd.org/\n.. _gh_discussions: https://github.com/python-semver/python-semver/discussions\n" }, { "path": "CONTRIBUTORS", "content": "############\nContributors\n############\n\nPython Semver library\n#####################\n\nThis document records the primary maintainers and significant\ncontributors to this code base.\n\nThank you to everyone whose work has made this possible.\n\n\nPrimary maintainers\n===================\n\n* Tom Schraitle \n* Sébastien Celles \n\nOld maintainer:\n\n* Kostiantyn Rybnikov \n\n\nList of Contributors\n====================\n\n(in alphabetical order)\n\n* Jelo Agnasin \n* Carles Barrobés \n* Eli Bishop \n* Peter Bittner \n* Craig Blaszczyk \n* Tyler Cross \n* Dennis Felsing \n* Ben Finney \n* Zane Geiger \n* T. Jameson Little \n* Raphael Krupinski \n* Thomas Laferriere \n* Zack Lalanne \n* Tuure Laurinolli \n* Damien Nadé \n* Jan Pieter Waagmeester \n* Alexander Puzynia \n* Lexi Robinson \n* robi-wan \n* George Sakkis \n* Mike Salvatore \n* sbrudenell \n* Alexander Shorin \n* Anton Talevnin \n* Karol Werner \n \n..\n Local variables:\n coding: utf-8\n mode: text\n mode: rst\n End:\n vim: fileencoding=utf-8 filetype=rst :\n" }, { "path": "LICENSE.txt", "content": "Copyright (c) 2013, Konstantine Rybnikov\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without modification,\nare permitted provided that the following conditions are met:\n\n Redistributions of source code must retain the above copyright notice, this\n list of conditions and the following disclaimer.\n\n Redistributions in binary form must reproduce the above copyright notice, this\n list of conditions and the following disclaimer in the documentation and/or\n other materials provided with the distribution.\n\n Neither the name of the python-semver org nor the names of its\n contributors may be used to endorse or promote products derived from\n this software without specific prior written permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND\nANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED\nWARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE\nDISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR\nANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\n(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;\nLOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON\nANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\n(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS\nSOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n" }, { "path": "MANIFEST.in", "content": "include *.md\ninclude *.rst\ninclude *.txt\ninclude CONTRIBUTORS\ninclude CITATION.cff\ninclude Makefile\ninclude changelog.d/*\ngraft docs/**\ninclude tests/*.py\ninclude tox.ini\ninclude .pytest.ini\ninclude .ruff.toml\ninclude uv.lock\n\n# The dot files:\ninclude .coveragerc\ninclude .editorconfig\ninclude .gitignore\ninclude .readthedocs.yaml\n\n\nprune docs/_build\nrecursive-exclude .github *\nprune docs/**/__pycache__\n\nglobal-exclude __pycache__\n" }, { "path": "Makefile", "content": "sdist:\n\tpython setup.py sdist bdist_wheel --universal\n\n.PHONY sdist\n\n" }, { "path": "README.rst", "content": "Quickstart\n==========\n\n.. teaser-begin\n\nA Python module to simplify `semantic versioning`_.\n\n|GHAction| |python-support| |downloads| |license| |docs| |black|\n|openissues| |GHDiscussion|\n\n.. teaser-end\n\nThe module follows the ``MAJOR.MINOR.PATCH`` style:\n\n* ``MAJOR`` version when you make incompatible API changes,\n* ``MINOR`` version when you add functionality in a backwards compatible manner, and\n* ``PATCH`` version when you make backwards compatible bug fixes.\n\nAdditional labels for pre-release and build metadata are supported.\n\nTo import this library, use:\n\n.. code-block:: python\n\n >>> import semver\n\nWorking with the library is quite straightforward. To turn a version string into the\ndifferent parts, use the ``semver.Version.parse`` function:\n\n.. code-block:: python\n\n >>> ver = semver.Version.parse('1.2.3-pre.2+build.4')\n >>> ver.major\n 1\n >>> ver.minor\n 2\n >>> ver.patch\n 3\n >>> ver.prerelease\n 'pre.2'\n >>> ver.build\n 'build.4'\n\nTo raise parts of a version, there are a couple of functions available for\nyou. The function ``semver.Version.bump_major`` leaves the original object untouched, but\nreturns a new ``semver.Version`` instance with the raised major part:\n\n.. code-block:: python\n\n >>> ver = semver.Version.parse(\"3.4.5\")\n >>> ver.bump_major()\n Version(major=4, minor=0, patch=0, prerelease=None, build=None)\n\nIt is allowed to concatenate different \"bump functions\":\n\n.. code-block:: python\n\n >>> ver.bump_major().bump_minor()\n Version(major=4, minor=1, patch=0, prerelease=None, build=None)\n\nTo compare two versions, semver provides the ``semver.compare`` function.\nThe return value indicates the relationship between the first and second\nversion:\n\n.. code-block:: python\n\n >>> semver.compare(\"1.0.0\", \"2.0.0\")\n -1\n >>> semver.compare(\"2.0.0\", \"1.0.0\")\n 1\n >>> semver.compare(\"2.0.0\", \"2.0.0\")\n 0\n\n\nThere are other functions to discover. Read on!\n\n\n.. |latest-version| image:: https://img.shields.io/pypi/v/semver.svg\n :alt: Latest version on PyPI\n :target: https://pypi.org/project/semver\n.. |python-support| image:: https://img.shields.io/pypi/pyversions/semver.svg\n :target: https://pypi.org/project/semver\n :alt: Python versions\n.. |downloads| image:: https://img.shields.io/pypi/dm/semver.svg\n :alt: Monthly downloads from PyPI\n :target: https://pypi.org/project/semver\n.. |license| image:: https://img.shields.io/pypi/l/semver.svg\n :alt: Software license\n :target: https://github.com/python-semver/python-semver/blob/master/LICENSE.txt\n.. |docs| image:: https://readthedocs.org/projects/python-semver/badge/?version=latest\n :target: http://python-semver.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n.. _semantic versioning: https://semver.org/\n.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://github.com/psf/black\n :alt: Black Formatter\n.. |Gitter| image:: https://badges.gitter.im/python-semver/community.svg\n :target: https://gitter.im/python-semver/community\n :alt: Gitter\n.. |openissues| image:: http://isitmaintained.com/badge/open/python-semver/python-semver.svg\n :target: http://isitmaintained.com/project/python-semver/python-semver\n :alt: Percentage of open issues\n.. |GHAction| image:: https://github.com/python-semver/python-semver/workflows/Python/badge.svg\n :alt: Python\n.. |GHDiscussion| image:: https://shields.io/badge/GitHub-%20Discussions-green?logo=github\n :target: https://github.com/python-semver/python-semver/discussions\n :alt: GitHub Discussion\n" }, { "path": "SUPPORT.md", "content": "# Getting support\n\nIf you need help, try these ways:\n\n* Ask your questions on the [discussion](https://github.com/python-semver/python-semver/discussions) page.\n\n Our forum is a good way to post your questions.\n* Read the [python-semver documentation](https://python-semver.readthedocs.io/).\n\n The documentation contains all the information to install and use the library.\n* Suggest a new feature or a new [issue](https://github.com/python-semver/python-semver/issues/new)\n\n If you found a problem or would like to suggest a new feature that could improve python-semver,\n this is the place to go.\n" }, { "path": "changelog.d/.gitignore", "content": "!.gitignore\n" }, { "path": "changelog.d/460.bugfix.rst", "content": ":meth:`~semver.version.Version.bump_prerelease` will now add `.0` to an\nexisting prerelease when the last segment of the current prerelease, split by\ndots (`.`), is not numeric. This is to ensure the new prerelease is considered\nhigher than the previous one.\n\n:meth:`~semver.version.Version.bump_prerelease` now also support an argument\n`bump_when_empty` which will bump the patch version if there is no existing\nprerelease, to ensure the resulting version is considered a higher version than\nthe previous one." }, { "path": "changelog.d/463.trivial.rst", "content": "Remove double code in :meth:`Version.bump_build`" }, { "path": "changelog.d/README.rst", "content": "The ``changelog.d`` Directory\n=============================\n\n.. This file is also included into the documentation\n\n.. -text-begin-\n\nA \"Changelog\" is a record of all notable changes made to a project. Such\na changelog, in our case the :file:`CHANGELOG.rst`, is read by our *users*.\nTherefor, any description should be aimed to users instead of describing\ninternal changes which are only relevant to developers.\n\nTo avoid merge conflicts, we use the `Towncrier`_ package to manage our changelog.\n\nThe directory :file:`changelog.d` contains \"newsfragments\" which are short\nReST-formatted files.\nOn release, those news fragments are compiled into our :file:`CHANGELOG.rst`.\n\nYou don't need to install ``towncrier`` yourself, use the :command:`tox` command\nto call the tool.\n\nWe recommend to follow the steps to make a smooth integration of your changes:\n\n#. After you have created a new pull request (PR), add a new file into the\n directory :file:`changelog.d`. Each filename follows the syntax::\n\n ..rst\n\n where ```` is the GitHub issue number.\n In case you have no issue but a pull request, prefix your number with ``pr``.\n ```` is one of:\n\n * ``bugfix``: fixes a reported bug.\n * ``deprecation``: informs about deprecation warnings\n * ``doc``: improves documentation.\n * ``feature``: adds new user facing features.\n * ``removal``: removes obsolete or deprecated features.\n * ``trivial``: fixes a small typo or internal change that might be noteworthy.\n\n For example: ``123.feature.rst``, ``pr233.removal.rst``, ``456.bugfix.rst`` etc.\n\n#. Create the new file with the command::\n\n tox -e changelog -- create 123.feature.rst\n\n The file is created int the :file:`changelog.d/` directory.\n\n#. Open the file and describe your changes in RST format.\n\n * Wrap symbols like modules, functions, or classes into double backticks\n so they are rendered in a ``monospace font``.\n * Prefer simple past tense or constructions with \"now\".\n\n#. Check your changes with::\n\n tox -e changelog -- check\n\n#. Optionally, build a draft version of the changelog file with the command::\n\n tox -e changelog\n\n#. Commit all your changes and push it.\n\n\nThis finishes your steps.\n\nOn release, the maintainer compiles a new :file:`CHANGELOG.rst` file by running::\n\n tox -e changelog -- build\n\nThis will remove all newsfragments inside the :file:`changelog.d` directory,\nmaking it ready for the next release.\n\n\n\n.. _Towncrier: https://pypi.org/project/towncrier\n" }, { "path": "changelog.d/_template.rst", "content": "{% for section, _ in sections.items() %}\n{% set underline = underlines[0] %}{% if section %}{{section}}\n{{ underline * section|length }}{% set underline = underlines[1] %}\n\n{% endif %}\n\n:Released: {{ versiondata.date }}\n:Maintainer:\n\n\n{% if sections[section] %}\n{% for category, val in definitions.items() if category in sections[section] %}\n{{ definitions[category]['name'] }}\n{{ underline * definitions[category]['name']|length }}\n\n{% if definitions[category]['showcontent'] %}\n{% for text, values in sections[section][category].items() %}\n{%- for value in values %}\n{% if value.startswith(\"pr\") %}\n* :pr:`{{ value[2:] }}`{% else %}\n* :gh:`{{ value[1:] }}`{% endif %}{%- endfor -%}: {{ text }}\n\n{% endfor %}\n\n{% else %}\n- {{ sections[section][category]['']|join(', ') }}\n\n{% endif %}\n{% if sections[section][category]|length == 0 %}\nNo significant changes.\n\n{% else %}\n{% endif %}\n\n{% endfor %}\n{% else %}\nNo significant changes.\n\n\n{% endif %}\n{% endfor %}\n----\n" }, { "path": "docs/Makefile", "content": "# Minimal makefile for Sphinx documentation\n#\n\n# You can set these variables from the command line.\nSPHINXOPTS =\nSPHINXBUILD = sphinx-build\nSPHINXPROJ = semver\nSOURCEDIR = .\nBUILDDIR = _build\n\n# Set the source directory for your project\nSRC_DIR = ../src\n\n# Set the PYTHONPATH environment variable\nexport PYTHONPATH := $(SRC_DIR):$(PYTHONPATH)\n\n# Put it first so that \"make\" without argument is like \"make help\".\nhelp:\n\t@$(SPHINXBUILD) -M help \"$(SOURCEDIR)\" \"$(BUILDDIR)\" $(SPHINXOPTS) $(O)\n\n.PHONY: help Makefile\n\n# Catch-all target: route all unknown targets to Sphinx using the new\n# \"make mode\" option. $(O) is meant as a shortcut for $(SPHINXOPTS).\n%: Makefile\n\t@$(SPHINXBUILD) -M $@ \"$(SOURCEDIR)\" \"$(BUILDDIR)\" $(SPHINXOPTS) $(O)\n" }, { "path": "docs/_static/css/custom.css", "content": "/*\nhttps://github.com/bitprophet/alabaster\n*/\n\n/* Roboto (Sans), Roboto Slab (\"serif\"), Roboto Mono*/\n@import url('https://fonts.googleapis.com/css2?family=Roboto+Mono:ital,wght@0,400;0,600;1,400&family=Roboto+Slab:wght@700&family=Roboto:ital@0;1&display=swap');\n\n.logo {\n font-family: \"Roboto Slab\";\n}\n\nimg.logo {\n width: 80%;\n}\n\ndiv.document {\n margin-top: 0pt;\n}\n\ndiv.related.top {\n margin-top: -1em;\n}\n\ndiv.related.top nav {\n margin-bottom: 0.5em;\n margin-top: 0.5em;\n}\n\n.sphinxsidebarwrapper .caption {\n margin-top: 1em;\n margin-bottom: -0.75em;\n}\n\n#searchbox {\n margin-bottom: 1.25em;\n}\n\n.section h1 {\n font-weight: 700;\n}\n\n.py.class {\n margin-top: 1.5em;\n}\n\n.py.method {\n padding-top: 0.25em;\n padding-bottom: 1.25em;\n border-top: 1px solid #EEE;\n}\n\n.py.function{\n padding-top: 1.25em;\n}\n\n.related.bottom {\n margin-top: 1em;\n}\n\nbody {\n font-weight: 400;\n}\n\nnav#rellinks {\n float: left;\n width: 100%;\n}\n\nnav#rellinks li:first-child {\n float: left;\n text-align: left;\n width: 50%;\n}\n\nnav#rellinks li:last-child {\n float: right;\n text-align: right;\n width: 50%;\n}\n\nnav#rellinks li+li:before {\n content: \"\";\n}\n\ndiv.related.top nav::after {\n float: none;\n}\n" }, { "path": "docs/_templates/layout.html", "content": "{#\n Import the theme's layout.\n#}\n{% extends \"!layout.html\" %}\n\n\n{%- block extrahead %}\n {{- super() }}\n \n{% endblock %}" }, { "path": "docs/advanced/coerce.py", "content": "import re\nfrom semver import Version\nfrom typing import Optional, Tuple\n\n\nBASEVERSION = re.compile(\n r\"\"\"[vV]?\n (?P0|[1-9]\\d*)\n (\\.\n (?P0|[1-9]\\d*)\n (\\.\n (?P0|[1-9]\\d*)\n )?\n )?\n \"\"\",\n re.VERBOSE,\n)\n\n\ndef coerce(version: str) -> Tuple[Version, Optional[str]]:\n \"\"\"\n Convert an incomplete version string into a semver-compatible Version\n object\n\n * Tries to detect a \"basic\" version string (``major.minor.patch``).\n * If not enough components can be found, missing components are\n set to zero to obtain a valid semver version.\n\n :param str version: the version string to convert\n :return: a tuple with a :class:`Version` instance (or ``None``\n if it's not a version) and the rest of the string which doesn't\n belong to a basic version.\n :rtype: tuple(:class:`Version` | None, str)\n \"\"\"\n match = BASEVERSION.search(version)\n if not match:\n return (None, version)\n\n ver = {\n key: 0 if value is None else value for key, value in match.groupdict().items()\n }\n ver = Version(**ver)\n rest = match.string[match.end() :] # noqa:E203\n return ver, rest\n" }, { "path": "docs/advanced/combine-pydantic-and-semver.rst", "content": "Combining Pydantic and semver\n=============================\n\n.. meta::\n :description lang=en:\n Combining Pydantic and semver\n\nAccording to its homepage, `Pydantic `_\n\"enforces type hints at runtime, and provides user friendly errors when data\nis invalid.\"\n\nIf you are working with Pydantic>2.0 and pydantic-extra-types>=2.10.5 use the built in `SemanticVersion` type, which wraps the :class:`Version ` class.\n\n .. code-block:: python\n\n from pydantic import BaseModel\n from pydantic_extra_types.semantic_version import SemanticVersion\n\n class appVersion(BaseModel):\n version: SemanticVersion\n \n app_version = appVersion(version=\"1.2.3\")\n\n print(app_version.version)\n # > 1.2.3\n\nTo work with Pydantic>2.0 and without pydantic-extra-types use the following example to define your own type:\n\n\n1. Derive a new class from :class:`~semver.version.Version`\n first and add the magic methods :py:meth:`__get_pydantic_core_schema__`\n and :py:meth:`__get_pydantic_json_schema__` like this:\n\n .. code-block:: python\n\n from typing import Annotated, Any, Callable\n from pydantic import GetJsonSchemaHandler\n from pydantic_core import core_schema\n from pydantic.json_schema import JsonSchemaValue\n from semver import Version\n\n\n class _VersionPydanticAnnotation:\n @classmethod\n def __get_pydantic_core_schema__(\n cls,\n _source_type: Any,\n _handler: Callable[[Any], core_schema.CoreSchema],\n ) -> core_schema.CoreSchema:\n def validate_from_str(value: str) -> Version:\n return Version.parse(value)\n\n from_str_schema = core_schema.chain_schema(\n [\n core_schema.str_schema(),\n core_schema.no_info_plain_validator_function(validate_from_str),\n ]\n )\n\n return core_schema.json_or_python_schema(\n json_schema=from_str_schema,\n python_schema=core_schema.union_schema(\n [\n core_schema.is_instance_schema(Version),\n from_str_schema,\n ]\n ),\n serialization = core_schema.to_string_ser_schema(),\n )\n\n @classmethod\n def __get_pydantic_json_schema__(\n cls, _core_schema: core_schema.CoreSchema, handler: GetJsonSchemaHandler\n ) -> JsonSchemaValue:\n return handler(core_schema.str_schema())\n\n ManifestVersion = Annotated[Version, _VersionPydanticAnnotation]\n\n2. Create a new model (in this example :class:`MyModel`) and derive\n it from :py:class:`pydantic:pydantic.BaseModel`:\n\n .. code-block:: python\n\n import pydantic\n\n class MyModel(pydantic.BaseModel):\n version: _VersionPydanticAnnotation\n\n3. Use your model like this:\n\n .. code-block:: python\n\n model = MyModel.parse_obj({\"version\": \"1.2.3\"})\n\n The attribute :py:attr:`model.version` will be an instance of\n :class:`~semver.version.Version`.\n If the version is invalid, the construction will raise a\n :py:class:`pydantic:pydantic_core.ValidationError`.\n" }, { "path": "docs/advanced/convert-pypi-to-semver.rst", "content": "Converting Versions between PyPI and semver\n===========================================\n\n.. meta::\n :description lang=en:\n Converting versions between PyPI and semver\n\n.. Link\n https://packaging.pypa.io/en/latest/_modules/packaging/version.html#InvalidVersion\n\nWhen packaging for PyPI, your versions are defined through `PEP 440`_.\nThis is the standard version scheme for Python packages and\nimplemented by the :class:`packaging.version.Version` class.\n\nHowever, these versions are different from semver versions\n(cited from `PEP 440`_):\n\n* The \"Major.Minor.Patch\" (described in this PEP as \"major.minor.micro\")\n aspects of semantic versioning (clauses 1-8 in the 2.0.0\n specification) are fully compatible with the version scheme defined\n in this PEP, and abiding by these aspects is encouraged.\n\n* Semantic versions containing a hyphen (pre-releases - clause 10)\n or a plus sign (builds - clause 11) are *not* compatible with this PEP\n and are not permitted in the public version field.\n\nIn other words, it's not always possible to convert between these different\nversioning schemes without information loss. It depends on what parts are\nused. The following table gives a mapping between these two versioning\nschemes:\n\n+--------------+----------------+\n| PyPI Version | Semver version |\n+==============+================+\n| ``epoch`` | n/a |\n+--------------+----------------+\n| ``major`` | ``major`` |\n+--------------+----------------+\n| ``minor`` | ``minor`` |\n+--------------+----------------+\n| ``micro`` | ``patch`` |\n+--------------+----------------+\n| ``pre`` | ``prerelease`` |\n+--------------+----------------+\n| ``dev`` | ``build`` |\n+--------------+----------------+\n| ``post`` | n/a |\n+--------------+----------------+\n\n\n.. _convert_pypi_to_semver:\n\nFrom PyPI to semver\n-------------------\n\nWe distinguish between the following use cases:\n\n\n* **\"Incomplete\" versions**\n\n If you only have a major part, this shouldn't be a problem.\n The initializer of :class:`semver.Version ` takes\n care to fill missing parts with zeros (except for major).\n\n .. code-block:: python\n\n >>> from packaging.version import Version as PyPIVersion\n >>> from semver import Version\n\n >>> p = PyPIVersion(\"3.2\")\n >>> p.release\n (3, 2)\n >>> Version(*p.release)\n Version(major=3, minor=2, patch=0, prerelease=None, build=None)\n\n* **Major, minor, and patch**\n\n This is the simplest and most compatible approch. Both versioning\n schemes are compatible without information loss.\n\n .. code-block:: python\n\n >>> p = PyPIVersion(\"3.0.0\")\n >>> p.base_version\n '3.0.0'\n >>> p.release\n (3, 0, 0)\n >>> Version(*p.release)\n Version(major=3, minor=0, patch=0, prerelease=None, build=None)\n\n* **With** ``pre`` **part only**\n\n A prerelease exists in both versioning schemes. As such, both are\n a natural candidate. A prelease in PyPI version terms is the same\n as a \"release candidate\", or \"rc\".\n\n .. code-block:: python\n\n >>> p = PyPIVersion(\"2.1.6.pre5\")\n >>> p.base_version\n '2.1.6'\n >>> p.pre\n ('rc', 5)\n >>> pre = \"\".join([str(i) for i in p.pre])\n >>> Version(*p.release, pre)\n Version(major=2, minor=1, patch=6, prerelease='rc5', build=None)\n\n* **With only development version**\n\n Semver doesn't have a \"development\" version.\n However, we could use Semver's ``build`` part:\n\n .. code-block:: python\n\n >>> p = PyPIVersion(\"3.0.0.dev2\")\n >>> p.base_version\n '3.0.0'\n >>> p.dev\n 2\n >>> Version(*p.release, build=f\"dev{p.dev}\")\n Version(major=3, minor=0, patch=0, prerelease=None, build='dev2')\n\n* **With a** ``post`` **version**\n\n Semver doesn't know the concept of a post version. As such, there\n is currently no way to convert it reliably.\n\n* **Any combination**\n\n There is currently no way to convert a PyPI version which consists\n of, for example, development *and* post parts.\n\n\nYou can use the following function to convert a PyPI version into\nsemver:\n\n.. code-block:: python\n\n def convert2semver(ver: packaging.version.Version) -> semver.Version:\n \"\"\"Converts a PyPI version into a semver version\n\n :param ver: the PyPI version\n :return: a semver version\n :raises ValueError: if epoch or post parts are used\n \"\"\"\n if not ver.epoch:\n raise ValueError(\"Can't convert an epoch to semver\")\n if not ver.post:\n raise ValueError(\"Can't convert a post part to semver\")\n\n pre = None if not ver.pre else \"\".join([str(i) for i in ver.pre])\n return semver.Version(*ver.release, prerelease=pre, build=ver.dev)\n\n\n.. _convert_semver_to_pypi:\n\nFrom semver to PyPI\n-------------------\n\nWe distinguish between the following use cases:\n\n\n* **Major, minor, and patch**\n\n .. code-block:: python\n\n >>> from packaging.version import Version as PyPIVersion\n >>> from semver import Version\n\n >>> v = Version(1, 2, 3)\n >>> PyPIVersion(str(v.finalize_version()))\n \n\n* **With** ``pre`` **part only**\n\n .. code-block:: python\n\n >>> v = Version(2, 1, 4, prerelease=\"rc1\")\n >>> PyPIVersion(str(v))\n \n\n* **With only development version**\n\n .. code-block:: python\n\n >>> v = Version(3, 2, 8, build=\"dev4\")\n >>> PyPIVersion(f\"{v.finalize_version()}{v.build}\")\n \n\nIf you are unsure about the parts of the version, the following\nfunction helps to convert the different parts:\n\n.. code-block:: python\n\n def convert2pypi(ver: semver.Version) -> packaging.version.Version:\n \"\"\"Converts a semver version into a version from PyPI\n\n A semver prerelease will be converted into a\n prerelease of PyPI.\n A semver build will be converted into a development\n part of PyPI\n :param semver.Version ver: the semver version\n :return: a PyPI version\n \"\"\"\n v = ver.finalize_version()\n prerelease = ver.prerelease if ver.prerelease else \"\"\n build = ver.build if ver.build else \"\"\n return PyPIVersion(f\"{v}{prerelease}{build}\")\n\n\n.. _PEP 440: https://www.python.org/dev/peps/pep-0440/\n" }, { "path": "docs/advanced/create-subclasses-from-version.rst", "content": ".. _sec_creating_subclasses_from_versioninfo:\n\nCreating Subclasses from Version\n================================\n\n.. meta::\n :description lang=en:\n Creating subclasses from Version class\n\nIf you do not like creating functions to modify the behavior of semver\n(as shown in section :ref:`sec_dealing_with_invalid_versions`), you can\nalso create a subclass of the :class:`Version ` class.\n\nFor example, if you want to output a \"v\" prefix before a version,\nbut the other behavior is the same, use the following code:\n\n.. literalinclude:: semverwithvprefix.py\n :language: python\n :lines: 4-\n\n\nThe derived class :class:`SemVerWithVPrefix` can be used like\nthe original class. Additionally, you can pass \"incomplete\"\nversion strings like ``v2.3``:\n\n.. code-block:: python\n\n >>> v1 = SemVerWithVPrefix.parse(\"v1.2.3\")\n >>> assert str(v1) == \"v1.2.3\"\n >>> print(v1)\n v1.2.3\n >>> v2 = SemVerWithVPrefix.parse(\"v2.3\")\n >>> v2 > v1\n True\n >>> bad = SemVerWithVPrefix.parse(\"1.2.4\")\n Traceback (most recent call last):\n ...\n ValueError: '1.2.4': not a valid semantic version tag. Must start with 'v' or 'V'\n" }, { "path": "docs/advanced/deal-with-invalid-versions.rst", "content": ".. _sec_dealing_with_invalid_versions:\n\nDealing with Invalid Versions\n=============================\n\n.. meta::\n :description lang=en:\n Dealing with invalid versions\n\nAs semver follows the semver specification, it cannot parse version\nstrings which are considered \"invalid\" by that specification. The semver\nlibrary cannot know all the possible variations so you need to help the\nlibrary a bit.\n\nFor example, if you have a version string ``v1.2`` would be an invalid\nsemver version.\nHowever, \"basic\" version strings consisting of major, minor,\nand patch part, can be easy to convert. The following function extract this\ninformation and returns a tuple with two items:\n\n.. literalinclude:: coerce.py\n :language: python\n\n\nThe function returns a *tuple*, containing a :class:`Version `\ninstance or None as the first element and the rest as the second element.\nThe second element (the rest) can be used to make further adjustments.\n\nFor example:\n\n.. code-block:: python\n\n >>> coerce(\"v1.2\")\n (Version(major=1, minor=2, patch=0, prerelease=None, build=None), '')\n >>> coerce(\"v2.5.2-bla\")\n (Version(major=2, minor=5, patch=2, prerelease=None, build=None), '-bla')\n" }, { "path": "docs/advanced/display-deprecation-warnings.rst", "content": ".. _sec_display_deprecation_warnings:\n\nDisplaying Deprecation Warnings\n===============================\n\n.. meta::\n :description lang=en:\n Displaying and filtering deprecation warnings\n\nBy default, deprecation warnings are `ignored in Python `_.\nThis also affects semver's own warnings.\n\nIt is recommended that you turn on deprecation warnings in your scripts. Use one of\nthe following methods:\n\n* Use the option `-Wd `_\n to enable default warnings:\n\n * Directly running the Python command::\n\n $ python3 -Wd scriptname.py\n\n * Add the option in the shebang line (something like ``#!/usr/bin/python3``)\n after the command::\n\n #!/usr/bin/python3 -Wd\n\n* In your own scripts add a filter to ensure that *all* warnings are displayed:\n\n .. code-block:: python\n\n import warnings\n warnings.simplefilter(\"default\")\n # Call your semver code\n\n For further details, see the section\n `Overriding the default filter `_\n of the Python documentation.\n" }, { "path": "docs/advanced/index.rst", "content": "Advanced topics\n===============\n\n.. meta::\n :description lang=en:\n Advanced topics for Python semver\n\n.. toctree::\n :maxdepth: 1\n\n deal-with-invalid-versions\n create-subclasses-from-version\n display-deprecation-warnings\n combine-pydantic-and-semver\n convert-pypi-to-semver\n version-from-file\n" }, { "path": "docs/advanced/semverwithvprefix.py", "content": "from semver import Version\n\n\nclass SemVerWithVPrefix(Version):\n \"\"\"\n A subclass of Version which allows a \"v\" prefix\n \"\"\"\n\n @classmethod\n def parse(cls, version: str) -> \"SemVerWithVPrefix\":\n \"\"\"\n Parse version string to a Version instance.\n\n :param version: version string with \"v\" or \"V\" prefix\n :raises ValueError: when version does not start with \"v\" or \"V\"\n :return: a new instance\n \"\"\"\n if not version[0] in (\"v\", \"V\"):\n raise ValueError(\n f\"{version!r}: not a valid semantic version tag. \"\n \"Must start with 'v' or 'V'\"\n )\n return super().parse(version[1:], optional_minor_and_patch=True)\n\n def __str__(self) -> str:\n # Reconstruct the tag\n return \"v\" + super().__str__()\n" }, { "path": "docs/advanced/version-from-file.rst", "content": ".. _sec_reading_versions_from_file:\n\nReading Versions from File\n==========================\n\n.. meta::\n :description lang=en:\n Reading versions from file\n\nIn cases where a version is stored inside a file, one possible solution\nis to use the following function:\n\n.. code-block:: python\n\n import os\n from typing import Union\n from semver.version import Version\n\n def get_version(path: Union[str, os.PathLike]) -> semver.Version:\n \"\"\"\n Construct a Version object from a file\n \n :param path: A text file only containing the semantic version\n :return: A :class:`Version` object containing the semantic\n version from the file.\n \"\"\"\n version = open(path,\"r\").read().strip()\n return Version.parse(version)\n" }, { "path": "docs/api.rst", "content": ".. _api:\n\nAPI Reference\n=============\n\n.. meta::\n :description lang=en:\n API reference about Python semver\n\n.. currentmodule:: semver\n\n\nMetadata :mod:`semver.__about__`\n--------------------------------\n\n.. automodule:: semver.__about__\n\n\nDeprecated Functions in :mod:`semver._deprecated`\n-------------------------------------------------\n\n.. automodule:: semver._deprecated\n\n.. autofunction:: semver._deprecated.compare\n\n.. autofunction:: semver._deprecated.bump_build\n\n.. autofunction:: semver._deprecated.bump_major\n\n.. autofunction:: semver._deprecated.bump_minor\n\n.. autofunction:: semver._deprecated.bump_patch\n\n.. autofunction:: semver._deprecated.bump_prerelease\n\n.. autofunction:: semver._deprecated.deprecated\n\n.. autofunction:: semver._deprecated.finalize_version\n\n.. autofunction:: semver._deprecated.format_version\n\n.. autofunction:: semver._deprecated.match\n\n.. autofunction:: semver._deprecated.max_ver\n\n.. autofunction:: semver._deprecated.min_ver\n\n.. autofunction:: semver._deprecated.parse\n\n.. autofunction:: semver._deprecated.parse_version_info\n\n.. autofunction:: semver._deprecated.replace\n\n\n\nCLI Parsing :mod:`semver.cli`\n-----------------------------\n\n.. automodule:: semver.cli\n\n.. autofunction:: semver.cli.cmd_bump\n\n.. autofunction:: semver.cli.cmd_check\n\n.. autofunction:: semver.cli.cmd_compare\n\n.. autofunction:: semver.cli.createparser\n\n.. autofunction:: semver.cli.main\n\n.. autofunction:: semver.cli.process\n\n\nEntry point :mod:`semver.__main__`\n----------------------------------\n\n.. automodule:: semver.__main__\n\n\n\nVersion Handling :mod:`semver.version`\n--------------------------------------\n\n.. automodule:: semver.version\n\n.. autoclass:: semver.version.VersionInfo\n\n.. autoclass:: semver.version.Version\n :members:\n :special-members: __iter__, __eq__, __ne__, __lt__, __le__, __gt__, __ge__, __getitem__, __hash__, __repr__, __str__\n" }, { "path": "docs/build-semver.rst", "content": ".. _build-semver:\n\nBuilding semver\n===============\n\n.. meta::\n :description lang=en:\n Building semver\n\n.. _Installing uv: https://docs.astral.sh/uv/getting-started/installation/\n\n\nThis project changed its way how it is built over time. We used to have\na :file:`setup.py` file, but switched to a :file:`pyproject.toml` setup.\n\nThe build process is managed by :command:`uv` command.\n\nYou need:\n\n* Python 3.7 or newer.\n\n* The :mod:`setuptools` module version 61 or newer which is used as\n a build backend.\n\n* The command :command:`uv` from Astral. Refer to the section\n `Installing uv`_ for more information.\n\n\nTo build semver, run::\n\n uv build\n\nAfter the command is finished, you can find two files in the :file:`dist` folder: a ``.tar.gz`` and a ``.whl`` file." }, { "path": "docs/changelog-semver3-devel.rst", "content": "\n#############################\nChangelog semver3 development\n#############################\n\nThis site contains all the changes during the development phase.\n\n.. _semver-3.0.0-dev.4:\n\nVersion 3.0.0-dev.4\n===================\n\n:Released: 2022-12-18\n:Maintainer:\n\n\n.. _semver-3.0.0-dev.4-bugfixes:\n\nBug Fixes\n---------\n\n* :gh:`374`: Correct Towncrier's config entries in the :file:`pyproject.toml` file.\n The old entries ``[[tool.towncrier.type]]`` are deprecated and need\n to be replaced by ``[tool.towncrier.fragment.]``.\n\n\n\n.. _semver-3.0.0-dev.4-deprecations:\n\nDeprecations\n------------\n\n* :gh:`372`: Deprecate support for Python 3.6.\n\n Python 3.6 reached its end of life and isn't supported anymore.\n At the time of writing (Dec 2022), the lowest version is 3.7.\n\n Although the `poll `_\n didn't cast many votes, the majority agree to remove support for\n Python 3.6.\n\n\n.. _semver-3.0.0-dev.4-doc:\n\nImproved Documentation\n----------------------\n\n* :gh:`335`: Add new section \"Converting versions between PyPI and semver\" the limitations\n and possible use cases to convert from one into the other versioning scheme.\n\n* :gh:`340`: Describe how to get version from a file\n\n* :gh:`343`: Describe combining Pydantic with semver in the \"Advanced topic\"\n section.\n\n* :gh:`350`: Restructure usage section. Create subdirectory \"usage/\" and splitted\n all section into different files.\n\n* :gh:`351`: Introduce new topics for:\n\n * \"Migration to semver3\"\n * \"Advanced topics\"\n\n\n.. _semver-3.0.0-dev.4-features:\n\nFeatures\n--------\n\n* :pr:`359`: Add optional parameter ``optional_minor_and_patch`` in :meth:`.Version.parse` to allow optional\n minor and patch parts.\n\n* :pr:`362`: Make :meth:`.Version.match` accept a bare version string as match expression, defaulting to\n equality testing.\n\n* :gh:`364`: Enhance :file:`pyproject.toml` to make it possible to use the\n :command:`pyproject-build` command from the build module.\n For more information, see :ref:`build-semver`.\n\n* :gh:`365`: Improve :file:`pyproject.toml`.\n\n * Use setuptools, add metadata. Taken approach from\n `A Practical Guide to Setuptools and Pyproject.toml\n `_.\n * Doc: Describe building of semver\n * Remove :file:`.travis.yml` in :file:`MANIFEST.in`\n (not needed anymore)\n * Distinguish between Python 3.6 and others in :file:`tox.ini`\n * Add skip_missing_interpreters option for :file:`tox.ini`\n * GH Action: Upgrade setuptools and setuptools-scm and test\n against 3.11.0-rc.2\n\n\n.. _semver-3.0.0-dev.4-internal:\n\nTrivial/Internal Changes\n------------------------\n\n* :gh:`378`: Fix some typos in Towncrier configuration\n\n\n\n----\n\n.. _semver-3.0.0-dev.3:\n\nVersion 3.0.0-dev.3\n===================\n\n:Released: 2022-01-19\n:Maintainer: Tom Schraitle\n\n\n.. _semver-3.0.0-dev.3-bugfixes:\n\nBug Fixes\n---------\n\n* :gh:`310`: Rework API documentation.\n Follow a more \"semi-manual\" attempt and add auto directives\n into :file:`docs/api.rst`.\n\n\n.. _semver-3.0.0-dev.3-docs:\n\nImproved Documentation\n----------------------\n\n* :gh:`312`: Rework \"Usage\" section.\n\n * Mention the rename of :class:`~semver.version.VersionInfo` to\n :class:`~semver.version.Version` class\n * Remove semver. prefix in doctests to make examples shorter\n * Correct some references to dunder methods like\n :func:`~semver.version.Version.__getitem__`,\n :func:`~semver.version.Version.__gt__` etc.\n * Remove inconsistencies and mention module level function as\n deprecated and discouraged from using\n * Make empty :py:class:`python:super` call in :file:`semverwithvprefix.py` example\n\n* :gh:`315`: Improve release procedure text\n\n\n.. _semver-3.0.0-dev.3-trivial:\n\nTrivial/Internal Changes\n------------------------\n\n* :gh:`309`: Some (private) functions from the :mod:`semver.version`\n module has been changed.\n\n The following functions got renamed:\n\n * function :func:`semver.version.comparator` got renamed to\n :func:`semver.version._comparator` as it is only useful\n inside the :class:`~semver.version.Version` class.\n * function :func:`semver.version.cmp` got renamed to\n :func:`semver.version._cmp` as it is only useful\n inside the :class:`~semver.version.Version` class.\n\n The following functions got integrated into the\n :class:`~semver.version.Version` class:\n\n * function :func:`semver.version._nat_cmd` as a classmethod\n * function :func:`semver.version.ensure_str`\n\n* :gh:`313`: Correct :file:`tox.ini` for ``changelog`` entry to skip\n installation for semver. This should speed up the execution\n of towncrier.\n\n* :gh:`316`: Comparisons of :class:`~semver.version.Version` class and other\n types return now a :py:data:`python:NotImplemented` constant instead\n of a :py:exc:`python:TypeError` exception.\n\n In the Python documentation, :py:data:`python:NotImplemented` recommends\n returning this constant when comparing with :py:meth:`__gt__ `, :py:meth:`__lt__ `,\n and other comparison operators \"to indicate that the operation is\n not implemented with respect to the other type\".\n\n* :gh:`319`: Introduce stages in :file:`.travis.yml`\n The config file contains now two stages: check and test. If\n check fails, the test stage won't be executed. This could\n speed up things when some checks fails.\n\n* :gh:`322`: Switch from Travis CI to GitHub Actions.\n\n* :gh:`347`: Support Python 3.10 in GitHub Action and other config files.\n\n\n\n----\n\n.. _semver-3.0.0-dev.2:\n\nVersion 3.0.0-dev.2\n===================\n\n:Released: 2020-11-01\n:Maintainer: Tom Schraitle\n\n\n.. _semver-3.0.0-dev.2-deprecations:\n\nDeprecations\n------------\n\n* :gh:`169`: Deprecate CLI functions not imported from :mod:`semver.cli`.\n\n\n.. _semver-3.0.0-dev.2-features:\n\nFeatures\n--------\n\n* :gh:`169`: Create semver package and split code among different modules in the packages.\n\n * Remove :file:`semver.py`\n * Create :file:`src/semver/__init__.py`\n * Create :file:`src/semver/cli.py` for all CLI methods\n * Create :file:`src/semver/_deprecated.py` for the ``deprecated`` decorator and other deprecated functions\n * Create :file:`src/semver/__main__.py` to allow calling the CLI using :command:`python -m semver`\n * Create :file:`src/semver/_types.py` to hold type aliases\n * Create :file:`src/semver/version.py` to hold the :class:`~semver.version.Version` class (old name :class:`~semver.version.VersionInfo`) and its utility functions\n * Create :file:`src/semver/__about__.py` for all the metadata variables\n\n* :gh:`305`: Rename :class:`~semver.version.VersionInfo` to :class:`~semver.version.Version` but keep an alias for compatibility\n\n\n.. _semver-3.0.0-dev.2-docs:\n\nImproved Documentation\n----------------------\n\n* :gh:`304`: Several improvements in documentation:\n\n * Reorganize API documentation.\n * Add migration chapter from semver2 to semver3.\n * Distinguish between changlog for version 2 and 3\n\n* :gh:`305`: Add note about :class:`~semver.version.Version` rename.\n\n\n.. _semver-3.0.0-dev.2-trivial:\n\nTrivial/Internal Changes\n------------------------\n\n* :gh:`169`: Adapted infrastructure code to the new project layout.\n\n * Replace :file:`setup.py` with :file:`setup.cfg` because the :file:`setup.cfg` is easier to use\n * Adapt documentation code snippets where needed\n * Adapt tests\n * Changed the ``deprecated`` to hardcode the ``semver`` package name in the warning.\n\n Increase coverage to 100% for all non-deprecated APIs\n\n* :gh:`304`: Support PEP-561 :file:`py.typed`.\n\n According to the mentioned PEP:\n\n \"Package maintainers who wish to support type checking\n of their code MUST add a marker file named :file:`py.typed`\n to their package supporting typing.\"\n\n Add package_data to :file:`setup.cfg` to include this marker in dist\n and whl file.\n\n\n\n----\n\n.. _semver-3.0.0-dev.1:\n\nVersion 3.0.0-dev.1\n===================\n\n:Released: 2020-10-26\n:Maintainer: Tom Schraitle\n\n\n.. _semver-3.0.0-dev.1-deprecations:\n\nDeprecations\n------------\n\n* :pr:`290`: For semver 3.0.0-alpha0:\n\n * Remove anything related to Python2\n * In :file:`tox.ini` and :file:`.travis.yml`\n Remove targets py27, py34, py35, and pypy.\n Add py38, py39, and nightly (allow to fail)\n * In :file:`setup.py` simplified file and remove\n ``Tox`` and ``Clean`` classes\n * Remove old Python versions (2.7, 3.4, 3.5, and pypy)\n from Travis\n\n* :gh:`234`: In :file:`setup.py` simplified file and remove\n ``Tox`` and ``Clean`` classes\n\n\n.. _semver-3.0.0-dev.1-features:\n\nFeatures\n--------\n\n* :pr:`290`: Create semver 3.0.0-alpha0\n\n * Update :file:`README.rst`, mention maintenance\n branch ``maint/v2``.\n * Remove old code mainly used for Python2 compatibility,\n adjusted code to support Python3 features.\n * Split test suite into separate files under :file:`tests/`\n directory\n * Adjust and update :file:`setup.py`. Requires Python >=3.6.*\n Extract metadata directly from source (affects all the :data:`~semver.__about__.__version__`,\n :data:`~semver.__about__.__author__` etc. variables)\n\n* :gh:`270`: Configure Towncrier (:pr:`273`:)\n\n * Add :file:`changelog.d/.gitignore` to keep this directory\n * Create :file:`changelog.d/README.rst` with some descriptions\n * Add :file:`changelog.d/_template.rst` as Towncrier template\n * Add ``[tool.towncrier]`` section in :file:`pyproject.toml`\n * Add \"changelog\" target into :file:`tox.ini`. Use it like\n :command:`tox -e changelog -- CMD` whereas ``CMD`` is a\n Towncrier command. The default :command:`tox -e changelog`\n calls Towncrier to create a draft of the changelog file\n and output it to stdout.\n * Update documentation and add include a new section\n \"Changelog\" included from :file:`changelog.d/README.rst`.\n\n* :gh:`276`: Document how to create a sublass from :class:`~semver.version.VersionInfo` class\n\n* :gh:`213`: Add typing information\n\n\n.. _semver-3.0.0-dev.1-bugfixes:\n\nBug Fixes\n---------\n\n* :gh:`291`: Disallow negative numbers in VersionInfo arguments\n for ``major``, ``minor``, and ``patch``.\n\n\n.. _semver-3.0.0-dev.1-docs:\n\nImproved Documentation\n----------------------\n\n* :pr:`290`: Several improvements in the documentation:\n\n * New layout to distinguish from the semver2 development line.\n * Create new logo.\n * Remove any occurances of Python2.\n * Describe changelog process with Towncrier.\n * Update the release process.\n\n\n.. _semver-3.0.0-dev.1-trivial:\n\nTrivial/Internal Changes\n------------------------\n\n* :pr:`290`: Add supported Python versions to :command:`black`.\n" }, { "path": "docs/changelog.rst", "content": ".. _change-log:\n\n.. include:: ../CHANGELOG.rst\n" }, { "path": "docs/conf.py", "content": "#!/usr/bin/env python3\n#\n# python-semver documentation build configuration file\n#\n# This file is execfile()d with the current directory set to its\n# containing dir.\n#\n# Note that not all possible configuration values are present in this\n# autogenerated file.\n#\n# All configuration values have a default; values that are commented out\n# serve to show the default.\n\n# If extensions (or modules to document with autodoc) are in another directory,\n# add these directories to sys.path here. If the directory is relative to the\n# documentation root, use os.path.abspath to make it absolute, like shown here.\n#\n\nimport os\nimport re\nfrom datetime import date\nfrom pathlib import Path\n\nSRC_DIR = Path(__file__).absolute().parent.parent / \"src\"\nYEAR = date.today().year\n\n\ndef find_version(path: Path) -> str:\n \"\"\"\n Build a path from *file_paths* and search for a ``__version__``\n string inside.\n \"\"\"\n content = Path(path).read_text(encoding=\"utf-8\")\n\n version_match = re.search(\n r\"^__version__ = ['\\\"]([^'\\\"]*)['\\\"]\",\n content,\n re.MULTILINE\n )\n if version_match:\n return version_match.group(1)\n\n raise RuntimeError(\"Unable to find version string.\")\n\n\n# -- General configuration ------------------------------------------------\n\n# If your documentation needs a minimal Sphinx version, state it here.\n#\n# needs_sphinx = '1.0'\n\n# Add any Sphinx extension module names here, as strings. They can be\n# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom\n# ones.\nextensions = [\n \"sphinx.ext.autodoc\",\n \"sphinx_autodoc_typehints\",\n \"sphinx.ext.intersphinx\",\n \"sphinx.ext.extlinks\",\n]\n\n# Autodoc configuration\nautoclass_content = \"class\"\nautodoc_typehints = \"signature\"\nautodoc_member_order = \"alphabetical\"\nadd_function_parentheses = True\n\n# Add any paths that contain templates here, relative to this directory.\ntemplates_path = [\"_templates\"]\n\n# The suffix(es) of source filenames.\n# You can specify multiple suffix as a list of string:\n#\nsource_suffix = \".rst\"\n\n# The master toctree document.\nmaster_doc = \"index\"\n\n# General information about the project.\nproject = \"python-semver\"\ncopyright = f\"{YEAR}, Kostiantyn Rybnikov and all\"\nauthor = \"Kostiantyn Rybnikov, Tom Schraitle, Sebastien Celles, and others\"\n\n# The version info for the project you're documenting, acts as replacement for\n# |version| and |release|, also used in various other places throughout the\n# built documents.\n#\n# The short X.Y version.\nrelease = find_version(SRC_DIR / \"semver/__about__.py\")\n# The full version, including alpha/beta/rc tags.\nversion = release # .rsplit(u\".\", 1)[0]\n\n# The language for content autogenerated by Sphinx. Refer to documentation\n# for a list of supported languages.\n#\n# This is also used if you do content translation via gettext catalogs.\n# Usually you set \"language\" from the command line for these cases.\nlanguage = \"en\"\n\n# List of patterns, relative to source directory, that match files and\n# directories to ignore when looking for source files.\n# This patterns also effect to html_static_path and html_extra_path\nexclude_patterns = [\"_build\", \"Thumbs.db\", \".DS_Store\"]\n\n# The name of the Pygments (syntax highlighting) style to use.\npygments_style = \"sphinx\"\n\n# If true, `todo` and `todoList` produce output, else they produce nothing.\ntodo_include_todos = False\n\n# Markup to shorten external links\n# See https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html\nextlinks = {\n \"gh\": (\"https://github.com/python-semver/python-semver/issues/%s\", \"#%s\"),\n \"pr\": (\"https://github.com/python-semver/python-semver/pull/%s\", \"PR #%s\"),\n}\n\n# Link to other projects’ documentation\n# See https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html\nintersphinx_mapping = {\n # Download it from the root with:\n # wget -O docs/inventories/python-objects.inv https://docs.python.org/3/objects.inv\n \"python\": (\"https://docs.python.org/3\", (None, \"inventories/python-objects.inv\")),\n # wget -O docs/inventories/pydantic.inv https://docs.pydantic.dev/latest/objects.inv\n \"pydantic\": (\n \"https://docs.pydantic.dev/latest/\",\n (None, \"inventories/pydantic.inv\"),\n ),\n}\n# Avoid side-effects (namely that documentations local references can\n# suddenly resolve to an external location.)\nintersphinx_disabled_reftypes = [\"*\"]\n\n# -- Options for HTML output ----------------------------------------------\n\n# The theme to use for HTML and HTML Help pages. See the documentation for\n# a list of builtin themes.\n#\nhtml_theme = \"alabaster\"\ntemplates_path = [\"_templates\"]\n\nGITHUB_URL = \"https://github.com/python-semver/python-semver\"\n\nhtml_theme_options = {\n # -- Basics\n #: Text blurb about your project to appear under the logo:\n # \"description\": \"Semantic versioning\",\n #: Makes the sidebar \"fixed\" or pinned in place:\n \"fixed_sidebar\": True,\n #: Relative path to $PROJECT/_static to logo image:\n \"logo\": \"logo.svg\",\n #: Set to true to insert your site's project name under\n #: the logo:\n # \"logo_name\": True,\n #: CSS width specifier controller default sidebar width:\n \"sidebar_width\": \"25%\",\n #: CSS width specifier controlling default content/page width:\n \"page_width\": \"auto\",\n #: CSS width specifier controlling default body text width:\n \"body_max_width\": \"auto\",\n #\n # -- Service Links and Badges\n #: Contains project name and user of GitHub:\n \"github_user\": \"python-semver\",\n \"github_repo\": \"python-semver\",\n #: whether to link to your GitHub:\n \"github_button\": True,\n #:\n \"github_type\": \"star\",\n #: whether to apply a \"Fork me on Github\" banner\n #: in the top right corner of the page:\n # \"github_banner\": True,\n #\n # -- Non-service sidebar control\n #: Dictionary mapping link names to link targets:\n \"extra_nav_links\": {\n \"PyPI\": \"https://pypi.org/project/semver/\",\n \"Libraries.io\": \"https://libraries.io/pypi/semver\",\n },\n #: Boolean determining whether all TOC entries that\n #: are not ancestors of the current page are collapsed:\n \"sidebar_collapse\": True,\n #\n # -- Header/footer options\n #: used to display next and previous links above and\n #: below the main page content\n \"show_relbars\": True,\n \"show_relbar_top\": True,\n #\n # -- Style colors\n # \"anchor\": \"\",\n # \"anchor_hover_bg\": \"\",\n # \"anchor_hover_fg\": \"\",\n \"narrow_sidebar_fg\": \"lightgray\",\n #\n # -- Fonts\n # \"code_font_size\": \"\",\n \"font_family\": \"'Roboto',sans-serif\",\n \"head_font_family\": \"'Roboto Slab',serif\",\n \"code_font_family\": \"'Roboto Mono',monospace\",\n \"font_size\": \"1.20rem\",\n}\n\nhtml_static_path = [\"_static\"]\nhtml_css_files = [\"css/custom.css\"]\n\nhtml_sidebars = {\n \"**\": [\n \"about.html\", # theme_logo\n # 'relations.html', # prev and next\n \"searchbox.html\", # basic/searchbox.html\n \"navigation.html\", # TOC\n # 'donate.html',\n ]\n}\n\n# Canonical link relation\nif os.environ.get(\"READTHEDOCS_CANONICAL_URL\"):\n html_baseurl = f\"{os.environ['READTHEDOCS_CANONICAL_URL']}\"\n\n# html_logo = \"logo.svg\"\n\n# -- Options for HTMLHelp output ------------------------------------------\n\n# Output file base name for HTML help builder.\nhtmlhelp_basename = \"semverdoc\"\n\n\n# -- Options for LaTeX output ---------------------------------------------\n\nlatex_elements = {\n # The paper size ('letterpaper' or 'a4paper').\n #\n # 'papersize': 'letterpaper',\n # The font size ('10pt', '11pt' or '12pt').\n #\n # 'pointsize': '10pt',\n # Additional stuff for the LaTeX preamble.\n #\n # 'preamble': '',\n # Latex figure (float) alignment\n #\n # 'figure_align': 'htbp',\n}\n\n# Grouping the document tree into LaTeX files. List of tuples\n# (source start file, target name, title,\n# author, documentclass [howto, manual, or own class]).\nlatex_documents = [\n (\n master_doc,\n \"semver.tex\",\n \"python-semver Documentation\",\n \"Kostiantyn Rybnikov and all\",\n \"manual\",\n )\n]\n\n\n# -- Options for manual page output ---------------------------------------\n\n# One entry per manual page. List of tuples\n# (source start file, name, description, authors, manual section).\nmanpage_doc = \"pysemver\"\n\nman_pages = [\n (\n manpage_doc,\n \"pysemver\",\n \"Helper script for Semantic Versioning\",\n [\"Thomas Schraitle\"],\n 1,\n )\n]\n\n\n# -- Options for Texinfo output -------------------------------------------\n\n# Grouping the document tree into Texinfo files. List of tuples\n# (source start file, target name, title, author,\n# dir menu entry, description, category)\ntexinfo_documents = [\n (\n master_doc,\n \"semver\",\n \"python-semver Documentation\",\n author,\n \"semver\",\n \"One line description of project.\",\n \"Miscellaneous\",\n )\n]\n" }, { "path": "docs/contribute/add-changelog-entry.rst", "content": ".. _add-changelog:\n\nAdding a Changelog Entry\n========================\n\n.. meta::\n :description lang=en:\n Adding a changelog entry with Towncrier\n\n.. include:: ../../changelog.d/README.rst\n :start-after: -text-begin-" }, { "path": "docs/contribute/doc-semver.rst", "content": ".. _doc:\n\nDocumenting semver\n==================\n\n.. meta::\n :description lang=en:\n Documenting semver with type annotations, docstrings, Sphinx directives\n\nDocumenting the features of semver is very important. It gives our developers\nan overview what is possible with semver, how it \"feels\", and how it is\nused efficiently.\n\n.. note::\n\n To build the documentation locally use the following command::\n\n $ tox -e docs\n\n The built documentation is available in :file:`docs/_build/html`.\n\n\nA new feature is *not* complete if it isn't proberly documented. A good\ndocumentation includes:\n\n * **Type annotations**\n\n This library supports type annotations. Therefore, each function\n or method requires types for each arguments and return objects.\n Exception of this rule is ``self``.\n\n * **A docstring**\n\n Each docstring contains a summary line, a linebreak, an optional\n directive (see next item), the description of its arguments in\n `Sphinx style`_, and an optional doctest.\n The docstring is extracted and reused in the :ref:`api` section.\n An appropriate docstring looks like this::\n\n def to_tuple(self) -> VersionTuple:\n \"\"\"\n Convert the Version object to a tuple.\n\n .. versionadded:: 2.10.0\n Renamed ``VersionInfo._astuple`` to ``VersionInfo.to_tuple`` to\n make this function available in the public API.\n\n :return: a tuple with all the parts\n\n >>> semver.Version(5, 3, 1).to_tuple()\n (5, 3, 1, None, None)\n\n \"\"\"\n\n * **An optional directive**\n\n If you introduce a new feature, change a function/method, or remove something,\n it is a good practice to introduce Sphinx directives into the docstring.\n This gives the reader an idea what version is affected by this change.\n\n The first required argument, ``VERSION``, defines the version when this change\n was introduced. You can choose from:\n\n * ``.. versionadded:: VERSION``\n\n Use this directive to describe a new feature.\n\n * ``.. versionchanged:: VERSION``\n\n Use this directive to describe when something has changed, for example,\n new parameters were added, changed side effects, different return values, etc.\n\n * ``.. deprecated:: VERSION``\n\n Use this directive when a feature is deprecated. Describe what should\n be used instead, if appropriate.\n\n\n Add such a directive *after* the summary line, as shown above.\n\n * **The documentation**\n\n A docstring is good, but in most cases it is too short. API documentation\n cannot replace good user documentation.\n Describe *how* to use your new feature in the documentation.\n Here you can give your readers more examples, describe it in a broader\n context, or show edge cases.\n\n\n.. _Sphinx style: https://sphinx-rtd-tutorial.rtfd.io/en/latest/docstrings.html\n" }, { "path": "docs/contribute/finish-release.rst", "content": ".. _finish-release:\n\nFinish the Release\n==================\n\n.. meta::\n :description lang=en:\n Finish the semver release by creating tags\n\n1. Create a tag:\n\n $ git tag -a x.x.x\n\n It’s recommended to use the generated Tox output from the Changelog.\n\n2. Push the tag:\n\n $ git push –tags\n\n3. In `GitHub Release\n page `_\n document the new release. Select the tag from the last step and copy\n the content of the tag description into the release description.\n\n4. Announce it in\n https://github.com/python-semver/python-semver/discussions/categories/announcements.\n\nYou’re done! Celebrate!\n" }, { "path": "docs/contribute/index.rst", "content": ".. _contributing:\n\nContributing to semver\n======================\n\n.. meta::\n :description lang=en:\n Contributing to Python semver\n\nThe semver source code is managed using Git and is hosted on GitHub::\n\n git clone git://github.com/python-semver/python-semver\n\n\n.. include:: prerequisites.rst\n :start-after: -text-begin-\n\n\n.. toctree::\n :maxdepth: 1\n :caption: More topics\n :includehidden:\n\n report-bugs\n run-test-suite\n doc-semver\n add-changelog-entry\n release-procedure\n finish-release\n\n\n.. _pull request: https://github.com/python-semver/python-semver/pulls\n" }, { "path": "docs/contribute/prerequisites.rst", "content": "Prerequisites\n-------------\n\n.. meta::\n :description lang=en:\n Overview of prerequisites for contributing\n\n.. -text-begin-\n\nBefore you make changes to the code, we would highly appreciate if you\nconsider the following general requirements:\n\n* Make sure your code adheres to the `Semantic Versioning`_ specification.\n\n* Check if your feature is covered by the Semantic Versioning specification.\n If not, ask on its GitHub project https://github.com/semver/semver.\n\n\n.. _Semantic Versioning: https://semver.org\n" }, { "path": "docs/contribute/release-procedure.rst", "content": "Release Procedure\n=================\n\n.. meta::\n :description lang=en:\n Release procedure: prepare and create the release\n\nThe following procedures gives a short overview of what steps are needed\nto create a new release.\n\nThese steps are interesting for the release manager only.\n\n\nPrepare the Release\n-------------------\n\n1. Verify that:\n\n - all issues for a new release are closed:\n https://github.com/python-semver/python-semver/issues.\n\n - all pull requests that should be included in this release are\n merged: https://github.com/python-semver/python-semver/pulls.\n\n - continuous integration for latest build was passing:\n https://github.com/python-semver/python-semver/actions.\n\n2. Create a new branch ``release/``.\n\n3. If one or several supported Python versions have been removed or\n added, verify that the following files have been updated:\n\n - :file:`setup.cfg`\n - :file:`tox.ini`\n - :file:`.git/workflows/pythonpackage.yml`\n - :file:`.github/workflows/python-testing.yml`\n\n4. Verify that the version in file :file:`src/semver/__about__.py`\n has been updated and follows the `Semver `_\n specification.\n\n5. Add eventually new contributor(s) to\n `CONTRIBUTORS `_.\n\n6. Check if all changelog entries are created. If some are missing,\n `create\n them `__.\n\n7. Show the new draft\n `CHANGELOG `_ entry for the latest release with:\n\n ::\n\n $ tox -e changelog\n\n Check the output. If you are not happy, update the files in the\n ``changelog.d/`` directory. If everything is okay, build the new\n ``CHANGELOG`` with:\n\n ::\n\n $ tox -e changelog -- build\n\n8. Build the documentation and check the output:\n\n ::\n\n $ tox -e docs\n\n9. Commit all changes, push, and create a pull request.\n\nCreate the New Release\n----------------------\n\n1. Ensure that long description\n (`README.rst `_)\n can be correctly rendered by Pypi using\n ``restview --long-description``\n\n2. Clean up your local Git repository. Be careful, as it **will remove\n all files** which are not versioned by Git:\n\n ::\n\n $ git clean -xfd\n\n Before you create your distribution files, clean the directory too:\n\n ::\n\n $ rm dist/*\n\n3. Create the distribution files (wheel and source):\n\n ::\n\n $ tox -e prepare-dist\n\n4. Upload the wheel and source to TestPyPI first:\n\n .. code:: bash\n\n $ twine upload --repository-url https://test.pypi.org/legacy/ dist/*\n\n If you have a ``~/.pypirc`` with a ``testpypi`` section, the upload\n can be simplified:\n\n ::\n\n $ twine upload --repository testpypi dist/*\n\n5. Check if everything is okay with the wheel. Check also the web site\n ``https://test.pypi.org/project//``\n\n6. If everything looks fine, merge the pull request.\n\n7. Upload to PyPI:\n\n .. code:: bash\n\n $ git clean -xfd\n $ tox -e prepare-dist\n $ twine upload dist/*\n\n8. Go to https://pypi.org/project/semver/ to verify that new version is\n online and the page is rendered correctly.\n\n" }, { "path": "docs/contribute/report-bugs.rst", "content": ".. _report-bugs:\n\nReporting Bugs and Asking Questions\n-----------------------------------\n\n.. meta::\n :description lang=en:\n Reporting bugs and asking questions about semver\n\nIf you think you have encountered a bug in semver or have an idea for a new\nfeature? Great! We like to hear from you!\n\nThere are several options to participate:\n\n* Open a new topic on our `GitHub discussion `_ page.\n Tell us our ideas or ask your questions.\n\n* Look into our GitHub `issues`_ tracker or open a new issue.\n\n\n.. _issues: https://github.com/python-semver/python-semver/issues\n.. _gh_discussions: https://github.com/python-semver/python-semver/discussions\n" }, { "path": "docs/contribute/run-test-suite.rst", "content": ".. _testsuite:\n\nRunning the Test Suite\n======================\n\n.. meta::\n :description lang=en:\n Running the test suite through tox\n\nWe use `pytest`_ and `tox`_ to run tests against all supported Python\nversions. All test dependencies are resolved automatically.\n\nYou can decide to run the complete test suite or only part of it:\n\n* To run all tests, use::\n\n $ tox\n\n If you have not all Python interpreters installed on your system\n it will probably give you some errors (``InterpreterNotFound``).\n To avoid such errors, use::\n\n $ tox --skip-missing-interpreters\n\n It is possible to use one or more specific Python versions. Use the ``-e``\n option and one or more abbreviations (``py37`` for Python 3.7,\n ``py38`` for Python 3.8 etc.)::\n\n $ tox -e py37\n $ tox -e py37,py38\n\n To get a complete list and a short description, run::\n\n $ tox -av\n\n* To run only a specific test, pytest requires the syntax\n ``TEST_FILE::TEST_FUNCTION``.\n\n For example, the following line tests only the function\n :func:`test_immutable_major` in the file :file:`test_bump.py` for all\n Python versions::\n\n $ tox -e py37 -- tests/test_bump.py::test_should_bump_major\n\n By default, pytest prints only a dot for each test function. To\n reveal the executed test function, use the following syntax::\n\n $ tox -- -v\n\n You can combine the specific test function with the ``-e`` option, for\n example, to limit the tests for Python 3.7 and 3.8 only::\n\n $ tox -e py37,py38 -- tests/test_bump.py::test_should_bump_major\n\nOur code is checked against formatting, style, type, and docstring issues\n(`black`_, `flake8`_, `mypy`_, and `docformatter`_).\nIt is recommended to run your tests in combination with :command:`checks`,\nfor example::\n\n $ tox -e checks,py37,py38\n\n\n.. _black: https://black.rtfd.io\n.. _docformatter: https://pypi.org/project/docformatter/\n.. _flake8: https://flake8.rtfd.io\n.. _mypy: http://mypy-lang.org/\n.. _pytest: http://pytest.org/\n.. _tox: https://tox.rtfd.org/\n" }, { "path": "docs/index.rst", "content": "Semver |version| -- Semantic Versioning\n=======================================\n\n.. meta::\n :description lang=en:\n Semantic versioning for Python\n\n.. include:: readme.rst\n\n\n.. toctree::\n :maxdepth: 2\n :caption: Contents\n :hidden:\n :numbered:\n\n build-semver\n install\n usage/index\n migration/index\n advanced/index\n contribute/index\n version-policy\n api\n\n.. toctree::\n :maxdepth: 2\n :caption: CLI\n :hidden:\n\n pysemver\n\n\n.. toctree::\n :maxdepth: 1\n :caption: Development\n :hidden:\n\n changelog\n changelog-semver3-devel\n\n\nIndices and Tables\n==================\n\n* :ref:`genindex`\n* :ref:`modindex`\n* :ref:`search`\n" }, { "path": "docs/install.rst", "content": "Installing semver\n=================\n\n.. meta::\n :description lang=en:\n Installing semver on the system\n\nRelease Policy\n--------------\n\nAs semver uses `Semantic Versioning`_, breaking changes are only introduced in major\nreleases (incremented ``X`` in \"X.Y.Z\").\nRefer to section :ref:`version-policy` for a general overview.\n\nFor users who want or need to stay with major 3 releases only, add the\nfollowing version restriction (:file:`setup.py`, :file:`requirements.txt`,\nor :file:`pyproject.toml`)::\n\n semver>=3,<4\n\nThis line avoids surprises. You will get any updates within the major 3 release like 3.1.x and above. However, you will never get an update for semver 4.0.0.\n\nFor users who have to stay with major 2 releases only, use the following line::\n\n semver>=2,<3\n\n\nWith Pip\n--------\n\n.. code-block:: bash\n :name: install-pip\n\n pip3 install semver\n\nIf you want to install this specific version (for example, 3.0.0), use the command :command:`pip`\nwith an URL and its version:\n\n.. parsed-literal::\n\n pip3 install git+https://github.com/python-semver/python-semver.git@3.0.0\n\n\nWith uv\n-------\n\nFirst, install the :command:`uv` command. Refer to https://docs.astral.sh/uv/getting-started/installation/ for more information.\n\nThen use the command :command:`uv` to install the package:\n\n.. code-block:: bash\n :name: install-uv\n\n uv pip install semver\n\n\nLinux Distributions\n-------------------\n\n.. note::\n\n Some Linux distributions can have outdated packages.\n These outdated packages does not contain the latest bug fixes or new features.\n If you need a newer package, you have these option:\n\n * Ask the maintainer to update the package.\n * Update the package for your favorite distribution and submit it.\n * Use a Python virtual environment and :command:`pip install`.\n\n\nArch Linux\n^^^^^^^^^^\n\n1. Enable the community repositories first:\n\n .. code-block:: ini\n\n [community]\n Include = /etc/pacman.d/mirrorlist\n\n2. Install the package::\n\n $ pacman -Sy python-semver\n\n\nDebian\n^^^^^^\n\n1. Update the package index::\n\n $ sudo apt-get update\n\n2. Install the package::\n\n $ sudo apt-get install python3-semver\n\n\nFedora\n^^^^^^\n\n.. code-block:: bash\n\n $ dnf install python3-semver\n\n\nFreeBSD\n^^^^^^^\n\n.. code-block:: bash\n\n $ pkg install py36-semver\n\nopenSUSE\n^^^^^^^^\n\n1. Enable the ``devel:languages:python`` repository of the Open Build Service::\n\n $ sudo zypper addrepo --refresh \\\n --name devel_languages_python \\\n \"https://download.opensuse.org/repositories/devel:/languages:/python/\\$releasever\"\n\n2. Install the package::\n\n $ sudo zypper install --repo devel_languages_python python3-semver\n\n\nUbuntu\n^^^^^^\n\n1. Update the package index::\n\n $ sudo apt-get update\n\n2. Install the package::\n\n $ sudo apt-get install python3-semver\n\n\n.. _semantic versioning: https://semver.org/\n" }, { "path": "docs/make.bat", "content": "@ECHO OFF\r\n\r\npushd %~dp0\r\n\r\nREM Command file for Sphinx documentation\r\n\r\nif \"%SPHINXBUILD%\" == \"\" (\r\n\tset SPHINXBUILD=python -msphinx\r\n)\r\nset SOURCEDIR=.\r\nset BUILDDIR=_build\r\nset SPHINXPROJ=semver\r\n\r\nif \"%1\" == \"\" goto help\r\n\r\n%SPHINXBUILD% >NUL 2>NUL\r\nif errorlevel 9009 (\r\n\techo.\r\n\techo.The Sphinx module was not found. Make sure you have Sphinx installed,\r\n\techo.then set the SPHINXBUILD environment variable to point to the full\r\n\techo.path of the 'sphinx-build' executable. Alternatively you may add the\r\n\techo.Sphinx directory to PATH.\r\n\techo.\r\n\techo.If you don't have Sphinx installed, grab it from\r\n\techo.http://sphinx-doc.org/\r\n\texit /b 1\r\n)\r\n\r\n%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%\r\ngoto end\r\n\r\n:help\r\n%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%\r\n\r\n:end\r\npopd\r\n" }, { "path": "docs/migration/index.rst", "content": "Migrating to semver3\n====================\n\n.. meta::\n :description lang=en:\n Migrating from semver version 2 to version 3\n\n.. toctree::\n :maxdepth: 1\n\n migratetosemver3\n replace-deprecated-functions.rst\n" }, { "path": "docs/migration/migratetosemver3.rst", "content": ".. _semver2-to-3:\n\nMigrating from semver2 to semver3\n=================================\n\n.. meta::\n :description lang=en:\n Migrating from semver2 to semver3\n\nThis section describes the visible differences for\nusers and how your code stays compatible for semver3.\nSome changes are backward incompatible.\n\nAlthough the development team tries to make the transition\nto semver3 as smooth as possible, at some point change\nis inevitable.\n\nFor a more detailed overview of all the changes, refer\nto our :ref:`change-log`.\n\n\nUse Version instead of VersionInfo\n----------------------------------\n\nThe :class:`~semver.version.VersionInfo` has been renamed to\n:class:`~semver.version.Version` to have a more succinct name.\nAn alias has been created to preserve compatibility but\nusing the old name has been deprecated and will be removed\nin future versions.\n\nIf you still need the old version, use this line:\n\n.. code-block:: python\n\n from semver.version import Version as VersionInfo\n\n\n\nUse semver.cli instead of semver\n--------------------------------\n\nAll functions related to CLI parsing are moved to :mod:`semver.cli`.\nIf you need such functions, like :meth:`~semver.cli.cmd_bump`,\nimport it from :mod:`semver.cli` in the future:\n\n.. code-block:: python\n\n from semver.cli import cmd_bump\n\n\nUse semver.Version.is_valid instead of semver.Version.isvalid\n-------------------------------------------------------------\n\nThe pull request :pr:`284` introduced the method :meth:`~semver.version.Version.is_compatible`. To keep consistency, the development team\ndecided to rename the :meth:`~semver.Version.isvalid` to :meth:`~semver.Version.is_valid`.\n" }, { "path": "docs/migration/replace-deprecated-functions.rst", "content": ".. _sec_replace_deprecated_functions:\n\nReplacing Deprecated Functions\n==============================\n\n.. meta::\n :description lang=en:\n Replacing deprecated functions\n\n.. versionchanged:: 2.10.0\n The development team of semver has decided to deprecate certain functions on\n the module level. The preferred way of using semver is through the\n :class:`~semver.version.Version` class.\n\nThe deprecated functions can still be used in version 2.10.0 and above.\nHowever, in future versions of semver, the deprecated functions will be removed.\n\n\nDeprecated Module Level Functions\n---------------------------------\n\nThe following list shows the deprecated module level functions and how you can replace\nthem with code which is compatible for future versions:\n\n* :func:`semver.bump_major `,\n :func:`semver.bump_minor `,\n :func:`semver.bump_patch `,\n :func:`semver.bump_prerelease `,\n :func:`semver.bump_build `\n\n Replace them with the respective methods of the :class:`~semver.version.Version`\n class.\n For example, the function :func:`semver.bump_major ` is replaced by\n :meth:`Version.bump_major ` and calling the ``str(versionobject)``:\n\n .. code-block:: python\n\n >>> s1 = semver.bump_major(\"3.4.5\")\n >>> s2 = str(Version.parse(\"3.4.5\").bump_major())\n >>> s1 == s2\n True\n\n Likewise with the other module level functions.\n\n* :func:`semver.finalize_version `\n\n Replace it with :meth:`Version.finalize_version `:\n\n .. code-block:: python\n\n >>> s1 = semver.finalize_version('1.2.3-rc.5')\n >>> s2 = str(semver.Version.parse('1.2.3-rc.5').finalize_version())\n >>> s1 == s2\n True\n\n* :func:`semver.format_version `\n\n Replace it with ``str(versionobject)``:\n\n .. code-block:: python\n\n >>> s1 = semver.format_version(5, 4, 3, 'pre.2', 'build.1')\n >>> s2 = str(Version(5, 4, 3, 'pre.2', 'build.1'))\n >>> s1 == s2\n True\n\n* :func:`semver.max_ver `\n\n Replace it with ``max(version1, version2, ...)`` or ``max([version1, version2, ...])`` and a ``key``:\n\n .. code-block:: python\n\n >>> s1 = semver.max_ver(\"1.2.3\", \"1.2.4\")\n >>> s2 = max(\"1.2.3\", \"1.2.4\", key=Version.parse)\n >>> s1 == s2\n True\n\n* :func:`semver.min_ver `\n\n Replace it with ``min(version1, version2, ...)`` or ``min([version1, version2, ...])`` and a ``key``:\n\n .. code-block:: python\n\n >>> s1 = semver.min_ver(\"1.2.3\", \"1.2.4\")\n >>> s2 = min(\"1.2.3\", \"1.2.4\", key=Version.parse)\n >>> s1 == s2\n True\n\n* :func:`semver.parse `\n\n Replace it with :meth:`Version.parse ` and call\n :meth:`Version.to_dict `:\n\n .. code-block:: python\n\n >>> v1 = semver.parse(\"1.2.3\")\n >>> v2 = Version.parse(\"1.2.3\").to_dict()\n >>> v1 == v2\n True\n\n* :func:`semver.parse_version_info `\n\n Replace it with :meth:`Version.parse `:\n\n .. code-block:: python\n\n >>> v1 = semver.parse_version_info(\"3.4.5\")\n >>> v2 = Version.parse(\"3.4.5\")\n >>> v1 == v2\n True\n\n* :func:`semver.replace `\n\n Replace it with :meth:`Version.replace `:\n\n .. code-block:: python\n\n >>> s1 = semver.replace(\"1.2.3\", major=2, patch=10)\n >>> s2 = str(Version.parse('1.2.3').replace(major=2, patch=10))\n >>> s1 == s2\n True\n\n\nDeprected Version methods\n-------------------------\n\nThe following list shows the deprecated methods of the :class:`~semver.version.Version` class.\n\n* :meth:`Version.isvalid `\n\n Replace it with :meth:`Version.is_valid `:\n\n\nDeprecated Classes\n------------------\n\n* :class:`VersionInfo `\n\n The class was renamed to :class:`~semver.version.Version`.\n Don't use the old name anymore." }, { "path": "docs/pysemver.rst", "content": ":orphan:\n\npysemver |version|\n==================\n\n.. meta::\n :description lang=en:\n Commandline tool pysemver describing all commands and options\n\nSynopsis\n--------\n\n.. _invocation:\n\n.. code:: bash\n\n pysemver