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