{"id":13468706,"url":"https://github.com/netromdk/vermin","last_synced_at":"2025-10-08T18:28:39.337Z","repository":{"id":38802851,"uuid":"122307726","full_name":"netromdk/vermin","owner":"netromdk","description":"Concurrently detect the minimum Python versions needed to run code","archived":false,"fork":false,"pushed_at":"2024-03-03T14:42:55.000Z","size":1671,"stargazers_count":475,"open_issues_count":10,"forks_count":26,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-31T19:09:07.769Z","etag":null,"topics":["abstract-syntax-tree","analysis","ast","concurrency","detection","multiprocessing","parser","python","python-2","python-3","source-code-analysis","version-checker"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/netromdk.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-02-21T08:03:38.000Z","updated_at":"2025-03-21T09:24:18.000Z","dependencies_parsed_at":"2024-06-18T15:28:13.688Z","dependency_job_id":"879571b7-af94-4ff2-af8f-ecccd1bee8e2","html_url":"https://github.com/netromdk/vermin","commit_stats":{"total_commits":753,"total_committers":16,"mean_commits":47.0625,"dds":0.3691899070385126,"last_synced_commit":"c661ded9389843257debb7778d1127667b72db56"},"previous_names":[],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netromdk%2Fvermin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netromdk%2Fvermin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netromdk%2Fvermin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netromdk%2Fvermin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/netromdk","download_url":"https://codeload.github.com/netromdk/vermin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247721898,"owners_count":20985084,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["abstract-syntax-tree","analysis","ast","concurrency","detection","multiprocessing","parser","python","python-2","python-3","source-code-analysis","version-checker"],"created_at":"2024-07-31T15:01:17.134Z","updated_at":"2025-10-08T18:28:34.302Z","avatar_url":"https://github.com/netromdk.png","language":"Python","readme":"|Test Status| |Analyze Status| |CodeQL Status| |Coverage| |PyPI version| |Commits since last| |Downloads| |CII best practices|\n\n.. |PyPI version| image:: https://badge.fury.io/py/vermin.svg\n   :target: https://pypi.python.org/pypi/vermin/\n\n.. |Test Status| image:: https://github.com/netromdk/vermin/workflows/Test/badge.svg?branch=master\n   :target: https://github.com/netromdk/vermin/actions\n\n.. |Analyze Status| image:: https://github.com/netromdk/vermin/workflows/Analyze/badge.svg?branch=master\n   :target: https://github.com/netromdk/vermin/actions\n\n.. |CodeQL Status| image:: https://github.com/netromdk/vermin/workflows/CodeQL/badge.svg?branch=master\n   :target: https://github.com/netromdk/vermin/security/code-scanning\n\n.. |Snyk Status| image:: https://github.com/netromdk/vermin/workflows/Snyk%20Schedule/badge.svg?branch=master\n   :target: https://github.com/netromdk/vermin/actions\n\n.. |Coverage| image:: https://coveralls.io/repos/github/netromdk/vermin/badge.svg?branch=master\n   :target: https://coveralls.io/github/netromdk/vermin?branch=master\n\n.. |Commits since last| image:: https://img.shields.io/github/commits-since/netromdk/vermin/latest.svg\n\n.. |Downloads| image:: https://static.pepy.tech/personalized-badge/vermin?period=total\u0026units=international_system\u0026left_color=gray\u0026right_color=blue\u0026left_text=Downloads\n   :target: https://pepy.tech/project/vermin\n\n.. |CII best practices| image:: https://bestpractices.coreinfrastructure.org/projects/6451/badge\n   :target: https://bestpractices.coreinfrastructure.org/projects/6451\n\nVermin\n******\n\nConcurrently detect the minimum Python versions needed to run code. Additionally, since the code is\nvanilla Python, and it doesn't have any external dependencies, it can be run with v3+ but still\nincludes detection of v2.x functionality.\n\nIt functions by parsing Python code into an abstract syntax tree (AST), which it traverses and\nmatches against internal dictionaries with **3796** rules, covering v2.0-2.7 and v3.0-3.12, divided\ninto **178** modules, **2614** classes/functions/constants members of modules, **875** kwargs of\nfunctions, **4** strftime directives, **3** bytes format directives, **2** array typecodes, **3**\ncodecs error handler names, **20** codecs encodings, **78** builtin generic annotation types, **9**\nbuiltin dict union (``|``) types, **8** builtin dict union merge (``|=``) types, and **2** user\nfunction decorators.\n\nBackports of the standard library, like ``typing``, can be enabled for better results. Get full list\nof backports via ``--help``.\n\nThe project is fairly well-tested with **4008** unit and integration tests that are executed on\nLinux, macOS, and Windows.\n\nIt is recommended to use the most recent Python version to run Vermin on projects since Python's own\nlanguage parser is used to detect language features, like f-strings since Python 3.6 etc.\n\n\nTable of Contents\n=================\n\n* `Usage \u003c#usage\u003e`__\n* `Features \u003c#features\u003e`__\n* `Caveats \u003c#caveats\u003e`__\n* `Configuration File \u003c#configuration-file\u003e`__\n* `Examples \u003c#examples\u003e`__\n* `Linting (showing only target versions violations) \u003c#linting-showing-only-target-versions-violations\u003e`__\n* `API (experimental) \u003c#api-experimental\u003e`__\n* `Analysis Exclusions \u003c#analysis-exclusions\u003e`__\n* `Parsable Output \u003c#parsable-output\u003e`__\n* `Contributing \u003c#contributing\u003e`__\n\nUsage\n=====\n\nIt is fairly straightforward to use Vermin.\n\nRunning it from the repository either directly or through specific interpreter::\n\n  % ./vermin.py /path/to/your/project        # (1) executing via `/usr/bin/env python`\n  % python3 vermin.py /path/to/your/project  # (2) specifically `python3`\n\nOr if installed via `PyPi \u003chttps://pypi.python.org/pypi/vermin/\u003e`__::\n\n  % pip install vermin\n  % vermin /path/to/your/project\n\n`Homebrew \u003chttps://brew.sh\u003e`__ (`pkg \u003chttps://formulae.brew.sh/formula/vermin#default\u003e`__)::\n\n  % brew install vermin\n\n`Spack \u003chttps://spack.io\u003e`__ (`pkg \u003chttps://github.com/spack/spack/blob/develop/var/spack/repos/builtin/packages/py-vermin/package.py\u003e`__)::\n\n  % git clone https://github.com/spack/spack.git\n  % . spack/share/spack/setup-env.sh  # depending on shell\n  % spack install py-vermin\n  % spack load py-vermin\n\n`Arch Linux (AUR) \u003chttps://aur.archlinux.org/packages/python-vermin/\u003e`__::\n\n  % yay -S python-vermin\n\nWhen using continuous integration (CI) tools, like `Travis CI \u003chttps://travis-ci.org/\u003e`_, Vermin can\nbe used to check that the minimum required versions didn't change. The following is an excerpt::\n\n  install:\n  - ./setup_virtual_env.sh\n  - pip install vermin\n  script:\n  - vermin -t=2.7 -t=3 project_package otherfile.py\n\nVermin can also be used as a `pre-commit \u003chttps://pre-commit.com/\u003e`__ hook:\n\n.. code-block:: yaml\n\n  repos:\n    - repo: https://github.com/netromdk/vermin\n      rev: GIT_SHA_OR_TAG  # ex: 'e88bda9' or 'v1.3.4'\n      hooks:\n        - id: vermin\n          # specify your target version here, OR in a Vermin config file as usual:\n          args: ['-t=3.8-', '--violations']\n          # (if your target is specified in a Vermin config, you may omit the 'args' entry entirely)\n\nWhen using the hook, a target version must be specified via a Vermin config file in your package,\nor via the ``args`` option in your ``.pre-commit-config.yaml`` config. If you're passing the target\nvia ``args``, it's recommended to also include ``--violations`` (shown above).\n\nIf you're using the ``vermin-all`` hook, you can specify any target as you usually would. However,\nif you're using the ``vermin`` hook, your target must be in the form of ``x.y-`` (as opposed to\n``x.y``), otherwise you will run into issues when your staged changes meet a minimum version that\nis lower than your target.\n\nSee the `pre-commit docs \u003chttps://pre-commit.com/#quick-start\u003e`__ for further general information\non how to get hooks set up on your project.\n\nFeatures\n========\n\nFeatures detected include v2/v3 ``print expr`` and ``print(expr)``, ``long``, f-strings, coroutines\n(``async`` and ``await``), asynchronous generators (``await`` and ``yield`` in same function),\nasynchronous comprehensions, ``await`` in comprehensions, asynchronous ``for``-loops, boolean\nconstants, named expressions, keyword-only parameters, positional-only parameters, ``nonlocal``,\n``yield from``, exception context cause (``raise .. from ..``), ``except*``, ``set`` literals,\n``set`` comprehensions, ``dict`` comprehensions, infix matrix multiplication, ``\"..\".format(..)``,\nimports (``import X``, ``from X import Y``, ``from X import *``), function calls wrt. name and\nkwargs, ``strftime`` + ``strptime`` directives used, function and variable annotations (also\n``Final`` and ``Literal``), ``continue`` in ``finally`` block, modular inverse ``pow()``, array\ntypecodes, codecs error handler names, encodings, ``%`` formatting and directives for bytes and\nbytearray, ``with`` statement, asynchronous ``with`` statement, multiple context expressions in a\n``with`` statement, multiple context expressions in a ``with`` statement grouped with parenthesis,\nunpacking assignment, generalized unpacking, ellipsis literal (``...``) out of slices, dictionary\nunion (``{..}  | {..}``), dictionary union merge (``a = {..}; a |= {..}``), builtin generic type\nannotations (``list[str]``), function decorators, class decorators, relaxed decorators,\n``metaclass`` class keyword, pattern matching with ``match``, union types written as ``X | Y``, and\ntype alias statements (``type X = SomeType``). It tries to detect and ignore user-defined functions,\nclasses, arguments, and variables with names that clash with library-defined symbols.\n\nCaveats\n=======\n\nFor frequently asked questions, check out the `FAQ discussions\n\u003chttps://github.com/netromdk/vermin/discussions/categories/faq\u003e`__.\n\nSelf-documenting fstrings detection has been disabled by default because the built-in AST cannot\ndistinguish ``f'{a=}'`` from ``f'a={a}'``, for instance, since it optimizes some information away\n(`#39 \u003chttps://github.com/netromdk/vermin/issues/39\u003e`__). And this incorrectly marks some source\ncode as using fstring self-doc when only using general fstring. To enable (unstable) fstring\nself-doc detection, use ``--feature fstring-self-doc``.\n\nDetecting union types (``X | Y`` `PEP 604 \u003chttps://www.python.org/dev/peps/pep-0604/\u003e`__) can be\ntricky because Vermin doesn't know all underlying details of constants and types since it parses and\ntraverses the AST. For this reason, heuristics are employed and this can sometimes yield incorrect\nresults (`#103 \u003chttps://github.com/netromdk/vermin/issues/103\u003e`__). To enable (unstable) union types\ndetection, use ``--feature union-types``.\n\nFunction and variable annotations aren't evaluated at definition time when ``from __future__ import\nannotations`` is used (`PEP 563 \u003chttps://www.python.org/dev/peps/pep-0563/\u003e`__). This is why\n``--no-eval-annotations`` is on by default (since v1.1.1, `#66\n\u003chttps://github.com/netromdk/vermin/issues/66\u003e`__). If annotations are being evaluated at runtime,\nlike using ``typing.get_type_hints`` or evaluating ``__annotations__`` of an object,\n``--eval-annotations`` should be used for best results.\n\nConfiguration File\n==================\n\nVermin automatically tries to detect a config file, starting in the current working directory where\nit is run, following parent folders until either the root or project boundary files/folders are\nreached. However, if ``--config-file`` is specified, no config is auto-detected and loaded.\n\nConfig file names being looked for: ``vermin.ini``, ``vermin.conf``, ``.vermin``, ``setup.cfg``\n\nProject boundary files/folders: ``.git``, ``.svn``, ``.hg``, ``.bzr``, ``_darcs``, ``.fslckout``,\n``.p4root``, ``.pijul``\n\nA sample config file can be found `here \u003csample.vermin.ini\u003e`__.\n\nNote that Vermin config can be in the same INI file as other configs, like the commonly used\n``setup.cfg``:\n\n.. code-block:: ini\n\n  [vermin]\n  verbose = 1\n  processes = 4\n\n  [flake8]\n  ignore = E111,F821\n\nExamples\n========\n\n.. code-block:: console\n\n  % ./vermin.py vermin\n  Minimum required versions: 3.0\n  Incompatible versions:     2\n\n  % ./vermin.py -t=3.3 vermin\n  Minimum required versions: 3.0\n  Incompatible versions:     2\n  Target versions not met:   3.3\n  % echo $?\n  1\n\n  % ./vermin.py --versions vermin\n  Minimum required versions: 3.0\n  Incompatible versions:     2\n  Version range:             2.0, 2.6, 2.7, 3.0\n\n  % ./vermin.py -v examples\n  Detecting python files..\n  Analyzing 6 files using 8 processes..\n               /path/to/examples/formatv2.py\n  2.7, 3.2     /path/to/examples/argparse.py\n  2.7, 3.0     /path/to/examples/formatv3.py\n  2.0, 3.0     /path/to/examples/printv3.py\n  !2, 3.4      /path/to/examples/abc.py\n               /path/to/examples/unknown.py\n  Minimum required versions:   3.4\n  Incompatible versions:         2\n\n  % ./vermin.py -vv /path/to/examples/abc.py\n  Detecting python files..\n  Analyzing using 8 processes..\n  !2, 3.4      /path/to/examples/abc.py\n    'abc' requires 2.6, 3.0\n    'abc.ABC' requires !2, 3.4\n\n  Minimum required versions: 3.4\n  Incompatible versions:     2\n\n  % ./vermin.py -vvv /path/to/examples/abc.py\n  Detecting python files..\n  Analyzing using 8 processes..\n  !2, 3.4      /path/to/examples/abc.py\n    L1 C7: 'abc' requires 2.6, 3.0\n    L2: 'abc.ABC' requires !2, 3.4\n\n  Minimum required versions: 3.4\n  Incompatible versions:     2\n\n  % ./vermin.py -f parsable /path/to/examples/abc.py\n  /path/to/examples/abc.py:1:7:2.6:3.0:'abc' module\n  /path/to/examples/abc.py:2::!2:3.4:'abc.ABC' member\n  /path/to/examples/abc.py:::!2:3.4:\n  :::!2:3.4:\n\nSee `Parsable Output \u003c#parsable-output\u003e`__ for more information about parsable output format.\n\nLinting: Showing only target versions violations\n================================================\n\nVermin shows lots of useful minimum version results when run normally, but it can also be used as a\nlinter to show only rules violating specified target versions by using ``--violations`` (or\n``--lint``) and one or two ``--target`` values. Verbosity level 2 is automatically set when showing\nonly violations, but can be increased if necessary. The final versions verdict is still calculated\nand printed at the end and the program exit code signifies whether the specified targets were met\n(``0``) or violated (``1``). However, if no rules are triggered the exit code will be ``0`` due to\ninconclusivity.\n\n.. code-block:: console\n\n  % cat test.py\n  import argparse  # 2.7, 3.2\n  all()            # 2.5, 3.0\n  enumerate()      # 2.3, 3.0\n\n  % ./vermin.py -t=2.4- -t=3 --violations test.py ; echo $?\n  Detecting python files..\n  Analyzing using 8 processes..\n  2.7, 3.2     test.py\n    'all' member requires 2.5, 3.0\n    'argparse' module requires 2.7, 3.2\n\n  Minimum required versions: 2.7, 3.2\n  Target versions not met:   2.4-, 3.0\n  1\n\nThe two first lines violate the targets but the third line matches and is therefore not shown.\n\nAPI (experimental)\n==================\n\nInformation such as minimum versions, used functionality constructs etc. can also be accessed\nprogrammatically via the ``vermin`` Python module, though it's an experimental feature. It is still\nrecommended to use the command-line interface.\n\n.. code-block:: python\n\n  \u003e\u003e\u003e import vermin as V\n  \u003e\u003e\u003e V.version_strings(V.detect(\"a = long(1)\"))\n  '2.0, !3'\n\n  \u003e\u003e\u003e config = V.Config()\n  \u003e\u003e\u003e config.add_exclusion(\"long\")\n  \u003e\u003e\u003e V.version_strings(V.detect(\"a = long(1)\", config))\n  '~2, ~3'\n\n  \u003e\u003e\u003e config.set_verbose(3)\n  \u003e\u003e\u003e v = V.visit(\"\"\"from argparse import ArgumentParser\n  ... ap = ArgumentParser(allow_abbrev=True)\n  ... \"\"\", config)\n  \u003e\u003e\u003e print(v.output_text(), end=\"\")\n  L1 C5: 'argparse' module requires 2.7, 3.2\n  L2: 'argparse.ArgumentParser(allow_abbrev)' requires !2, 3.5\n  \u003e\u003e\u003e V.version_strings(v.minimum_versions())\n  '!2, 3.5'\n\nAnalysis Exclusions\n===================\n\nAnalysis exclusion can be necessary in certain cases. The argument ``--exclude \u003cname\u003e`` (multiple\ncan be specified) can be used to exclude modules, members, kwargs, codecs error handler names, or\ncodecs encodings by name from being analysed via . Consider the following code block that checks if\n``PROTOCOL_TLS`` is an attribute of ``ssl``:\n\n.. code-block:: python\n\n  import ssl\n  tls_version = ssl.PROTOCOL_TLSv1\n  if hasattr(ssl, \"PROTOCOL_TLS\"):\n    tls_version = ssl.PROTOCOL_TLS\n\nIt will state that \"'ssl.PROTOCOL_TLS' requires 2.7, 3.6\" but to exclude that from the results, use\n``--exclude 'ssl.PROTOCOL_TLS'``. Afterwards, only \"'ssl' requires 2.6, 3.0\" will be shown and the\nfinal minimum required versions are v2.6 and v3.0 instead of v2.7 and v3.6.\n\nCode can even be excluded on a more fine grained level using the ``# novermin`` or ``# novm``\ncomments at line level. The following yields the same behavior as the previous code block, but only\nfor that particular ``if`` and its body:\n\n.. code-block:: python\n\n  import ssl\n  tls_version = ssl.PROTOCOL_TLSv1\n  if hasattr(ssl, \"PROTOCOL_TLS\"):  # novermin\n    tls_version = ssl.PROTOCOL_TLS\n\nIn scenarios where multiple tools are employed that use comments for various features, exclusions\ncan be defined by having ``#`` for each comment \"segment\":\n\n.. code-block:: python\n\n  if hasattr(ssl, \"PROTOCOL_TLS\"):  # noqa # novermin # pylint: disable=no-member\n    tls_version = ssl.PROTOCOL_TLS\n\nNote that if a code base does not have any occurrences of ``# novermin`` or ``# novm``, speedups up\nto 30-40%+ can be achieved by using the ``--no-parse-comments`` argument or ``parse_comments = no``\nconfig setting.\n\nParsable Output\n===============\n\nFor scenarios where the results of Vermin output is required, it is recommended to use the parsable\noutput format (``--format parsable``) instead of the default output. With this format enabled, each\nline will be on the form:\n\n.. code-block::\n\n  \u003cfile\u003e:\u003cline\u003e:\u003ccolumn\u003e:\u003cpy2\u003e:\u003cpy3\u003e:\u003cfeature\u003e\n\nThe ``\u003cline\u003e`` and ``\u003ccolumn\u003e`` are only shown when the verbosity level is high enough, otherwise\nthey are empty.\n\nEach feature detected per processed file will have the ``\u003cfeature\u003e`` defined on an individual\nline. The last line of the processed file will have a special line with the corresponding ``\u003cfile\u003e``\nand no ``\u003cfeature\u003e``, constituting the minimum versions of that file:\n\n.. code-block::\n\n   \u003cfile\u003e:::\u003cpy2\u003e:\u003cpy3\u003e:\n\nThe very last line is the final minimum versions results of the entire scan and therefore has no\n``\u003cfile\u003e`` and ``\u003cfeature\u003e``:\n\n.. code-block::\n\n   :::\u003cpy2\u003e:\u003cpy3\u003e:\n\nInspection of example output\n----------------------------\n\n.. code-block:: console\n\n  % ./vermin.py -f parsable /path/to/project\n  /path/to/project/abc.py:1:7:2.6:3.0:'abc' module\n  /path/to/project/abc.py:2::!2:3.4:'abc.ABC' member\n  /path/to/project/abc.py:::!2:3.4:\n  /path/to/project/except_star.py:::~2:~3:\n  /path/to/project/annotations.py:::2.0:3.0:print(expr)\n  /path/to/project/annotations.py:1::!2:3.0:annotations\n  /path/to/project/annotations.py:::!2:3.0:\n  :::!2:3.4:\n\n``abc.py`` requires ``!2`` and ``3.4`` via:\n\n.. code-block::\n\n  /path/to/project/abc.py:::!2:3.4:\n\n``except_star.py`` requires ``~2`` and ``~3`` via:\n\n.. code-block::\n\n  /path/to/project/except_star.py:::~2:~3:\n\nAnd ``annotations.py`` requires ``!2`` and ``3.0`` via:\n\n.. code-block::\n\n  /path/to/project/annotations.py:::!2:3.0:\n\nThat means that the final result is ``!2`` and ``3.4``, which is shown by the last line:\n\n.. code-block::\n\n  :::!2:3.4:\n\nContributing\n============\n\nContributions are very welcome, especially adding and updating detection rules of modules,\nfunctions, classes etc. to cover as many Python versions as possible. See `CONTRIBUTING.md\n\u003cCONTRIBUTING.md\u003e`__ for more information.\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetromdk%2Fvermin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetromdk%2Fvermin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetromdk%2Fvermin/lists"}