Introduction
============
hacking is a set of flake8 plugins that test and enforce the
`OpenStack StyleGuide <https://docs.openstack.org/hacking/latest/user/hacking.html#styleguide>`_
Hacking pins its dependencies, as a new release of some dependency can break
hacking based gating jobs. This is because new versions of dependencies can
introduce new rules, or make existing rules stricter.
Installation
============
hacking is available from pypi, so just run::
pip install hacking
This will install specific versions of ``flake8`` with the ``hacking``,
``pep8``, ``mccabe`` and ``pyflakes`` plugins.
Origin
======
Hacking started its life out as a text file in Nova's first commit. It was
initially based on the `Google Python Style Guide`_, and over time more
OpenStack specific rules were added. Hacking serves several purposes:
1. Agree on a common style guide so reviews don't get bogged down on style
nit picks. (example: docstring guidelines)
2. Make code written by many different authors easier to read by making the
style more uniform. (example: unix vs windows newlines)
3. Call out dangerous patterns and avoid them. (example: shadowing built-in
or reserved words)
Initially the hacking style guide was enforced manually by reviewers, but this
was a big waste of time so hacking, the tool, was born to automate
the process and remove the extra burden from human reviewers.
.. _`Google Python Style Guide`: https://google.github.io/styleguide/pyguide.html
Versioning
==========
hacking uses the ``major.minor.maintenance`` release notation, where maintenance
releases cannot contain new checks. This way projects can gate on hacking
by pinning on the ``major.minor`` number while accepting maintenance updates
without being concerned that a new version will break the gate with a new
check.
For example a project can depend on ``hacking>=0.10.0,<0.11.0``, and can know
that ``0.10.1`` will not fail in places where ``0.10.0`` passed.
Adding additional checks
========================
Each check is a pep8 plugin so read
- https://github.com/jcrocholl/pep8/blob/master/docs/developer.rst#contribute
The focus of new or changed rules should be to do one of the following
- Substantially increase the reviewability of the code (eg: H301, H303)
as they make it easy to understand where symbols come from)
- Catch a common programming error that may arise in the future (H201)
- Prevent a situation that would 100% of the time be -1ed by
developers (H903)
But, as always, remember that these are Guidelines. Treat them as
such. There are always times for exceptions. All new rules should
support noqa.
If a check needs to be staged in, or it does not apply to every project or its
branch, it can be added as off by default.
Requirements
------------
- The check must already have community support. We do not want to dictate
style, only enforce it.
- The canonical source of the OpenStack Style Guidelines is
`StyleGuide <https://docs.openstack.org/hacking/latest/user/hacking.html#styleguide>`_,
and hacking just enforces
them; so when adding a new check, it must be in ``HACKING.rst``
- False negatives are ok, but false positives are not
- Cannot be project specific, project specific checks should be `Local Checks`_
- Include extensive tests
- Registered as entry_points in ``setup.cfg``
- Error code must be in the relevant ``Hxxx`` group
- The check should not attempt to import modules from the code being checked.
Importing random modules, has caused all kinds of trouble for us in the past.
Enabling off-by-default checks
==============================
Some of the available checks are disabled by default. These checks are:
- [H106] Don't put vim configuration in source files.
- [H203] Use assertIs(Not)None to check for None.
- [H204] Use assert(Not)Equal to check for equality.
- [H205] Use assert(Greater|Less)(Equal) for comparison.
- [H210] Require 'autospec', 'spec', or 'spec_set' in
mock.patch/mock.patch.object calls
- [H904] Delay string interpolations at logging calls.
To enable these checks, edit the ``flake8`` section of the ``tox.ini`` file.
For example to enable H106 and H203:
.. code-block:: ini
[flake8]
enable-extensions = H106,H203
Local Checks
============
hacking supports having local changes in a source tree. They need to
be registered individually in tox.ini:
Add to tox.ini a new section `flake8:local-plugins` and list each plugin with
its entry-point. Additionally, you can add the path to the files
containing the plugins so that the repository does not need to be
installed with the `paths` directive.
.. code-block:: ini
[flake8:local-plugins]
extension =
N307 = checks:import_no_db_in_virt
N325 = checks:CheckForStrUnicodeExc
paths =
./nova/hacking
The plugins, in the example above they live in
`nova/hacking/checks.py`, need to annotate all functions with `@core.flake8ext`
.. code-block:: python
from hacking import core
...
@core.flake8ext
def import_no_db_in_virt(logical_line, filename):
...
class CheckForStrUnicodeExc(BaseASTChecker):
name = "check_for_str_unicode_exc"
version = "1.0"
...
Further details are part of the `flake8 documentation
<https://flake8.pycqa.org/en/latest/plugin-development/index.html>`_.
Raw data
{
"_id": null,
"home_page": "https://docs.openstack.org/hacking/latest/",
"name": "hacking",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "OpenStack",
"author_email": "openstack-discuss@lists.openstack.org",
"download_url": "https://files.pythonhosted.org/packages/f7/19/cf7a61cb63288c226bf2fa012ddcda51e4baad3039dbb4fc4b4e1a2b8e16/hacking-7.0.0.tar.gz",
"platform": null,
"description": "Introduction\n============\n\nhacking is a set of flake8 plugins that test and enforce the\n`OpenStack StyleGuide <https://docs.openstack.org/hacking/latest/user/hacking.html#styleguide>`_\n\nHacking pins its dependencies, as a new release of some dependency can break\nhacking based gating jobs. This is because new versions of dependencies can\nintroduce new rules, or make existing rules stricter.\n\nInstallation\n============\n\nhacking is available from pypi, so just run::\n\n pip install hacking\n\nThis will install specific versions of ``flake8`` with the ``hacking``,\n``pep8``, ``mccabe`` and ``pyflakes`` plugins.\n\nOrigin\n======\n\nHacking started its life out as a text file in Nova's first commit. It was\ninitially based on the `Google Python Style Guide`_, and over time more\nOpenStack specific rules were added. Hacking serves several purposes:\n\n1. Agree on a common style guide so reviews don't get bogged down on style\n nit picks. (example: docstring guidelines)\n2. Make code written by many different authors easier to read by making the\n style more uniform. (example: unix vs windows newlines)\n3. Call out dangerous patterns and avoid them. (example: shadowing built-in\n or reserved words)\n\nInitially the hacking style guide was enforced manually by reviewers, but this\nwas a big waste of time so hacking, the tool, was born to automate\nthe process and remove the extra burden from human reviewers.\n\n.. _`Google Python Style Guide`: https://google.github.io/styleguide/pyguide.html\n\nVersioning\n==========\n\nhacking uses the ``major.minor.maintenance`` release notation, where maintenance\nreleases cannot contain new checks. This way projects can gate on hacking\nby pinning on the ``major.minor`` number while accepting maintenance updates\nwithout being concerned that a new version will break the gate with a new\ncheck.\n\nFor example a project can depend on ``hacking>=0.10.0,<0.11.0``, and can know\nthat ``0.10.1`` will not fail in places where ``0.10.0`` passed.\n\n\nAdding additional checks\n========================\n\nEach check is a pep8 plugin so read\n\n- https://github.com/jcrocholl/pep8/blob/master/docs/developer.rst#contribute\n\nThe focus of new or changed rules should be to do one of the following\n\n- Substantially increase the reviewability of the code (eg: H301, H303)\n as they make it easy to understand where symbols come from)\n- Catch a common programming error that may arise in the future (H201)\n- Prevent a situation that would 100% of the time be -1ed by\n developers (H903)\n\nBut, as always, remember that these are Guidelines. Treat them as\nsuch. There are always times for exceptions. All new rules should\nsupport noqa.\n\nIf a check needs to be staged in, or it does not apply to every project or its\nbranch, it can be added as off by default.\n\nRequirements\n------------\n- The check must already have community support. We do not want to dictate\n style, only enforce it.\n- The canonical source of the OpenStack Style Guidelines is\n `StyleGuide <https://docs.openstack.org/hacking/latest/user/hacking.html#styleguide>`_,\n and hacking just enforces\n them; so when adding a new check, it must be in ``HACKING.rst``\n- False negatives are ok, but false positives are not\n- Cannot be project specific, project specific checks should be `Local Checks`_\n- Include extensive tests\n- Registered as entry_points in ``setup.cfg``\n- Error code must be in the relevant ``Hxxx`` group\n- The check should not attempt to import modules from the code being checked.\n Importing random modules, has caused all kinds of trouble for us in the past.\n\n\nEnabling off-by-default checks\n==============================\n\nSome of the available checks are disabled by default. These checks are:\n\n- [H106] Don't put vim configuration in source files.\n- [H203] Use assertIs(Not)None to check for None.\n- [H204] Use assert(Not)Equal to check for equality.\n- [H205] Use assert(Greater|Less)(Equal) for comparison.\n- [H210] Require 'autospec', 'spec', or 'spec_set' in\n mock.patch/mock.patch.object calls\n- [H904] Delay string interpolations at logging calls.\n\nTo enable these checks, edit the ``flake8`` section of the ``tox.ini`` file.\nFor example to enable H106 and H203:\n\n.. code-block:: ini\n\n [flake8]\n enable-extensions = H106,H203\n\nLocal Checks\n============\n\nhacking supports having local changes in a source tree. They need to\nbe registered individually in tox.ini:\n\nAdd to tox.ini a new section `flake8:local-plugins` and list each plugin with\nits entry-point. Additionally, you can add the path to the files\ncontaining the plugins so that the repository does not need to be\ninstalled with the `paths` directive.\n\n.. code-block:: ini\n\n [flake8:local-plugins]\n extension =\n N307 = checks:import_no_db_in_virt\n N325 = checks:CheckForStrUnicodeExc\n paths =\n ./nova/hacking\n\nThe plugins, in the example above they live in\n`nova/hacking/checks.py`, need to annotate all functions with `@core.flake8ext`\n\n.. code-block:: python\n\n from hacking import core\n ...\n @core.flake8ext\n def import_no_db_in_virt(logical_line, filename):\n ...\n\n class CheckForStrUnicodeExc(BaseASTChecker):\n name = \"check_for_str_unicode_exc\"\n version = \"1.0\"\n ...\n\nFurther details are part of the `flake8 documentation\n<https://flake8.pycqa.org/en/latest/plugin-development/index.html>`_.\n\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "OpenStack Hacking Guideline Enforcement",
"version": "7.0.0",
"project_urls": {
"Bug Tracker": "https://bugs.launchpad.net/hacking",
"CI": "https://zuul.opendev.org/t/openstack/builds?project=openstack%2Fhacking",
"Homepage": "https://docs.openstack.org/hacking/latest/",
"Reviews": "https://review.opendev.org/q/p:openstack/hacking+status:open",
"Source Code": "https://opendev.org/openstack/hacking"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "32139a50cf96a212c760c11e65541bd32fcdc7c6648a9a18d186f02d65adafd0",
"md5": "7d3ed2859066d1a654da6c13af1d820f",
"sha256": "4a5f5a1ef1c03e7ee244eb2d296181a5e07d1f3d64f706cf2c9a9542fa1f256d"
},
"downloads": -1,
"filename": "hacking-7.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7d3ed2859066d1a654da6c13af1d820f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 40105,
"upload_time": "2024-08-16T16:13:46",
"upload_time_iso_8601": "2024-08-16T16:13:46.402387Z",
"url": "https://files.pythonhosted.org/packages/32/13/9a50cf96a212c760c11e65541bd32fcdc7c6648a9a18d186f02d65adafd0/hacking-7.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f719cf7a61cb63288c226bf2fa012ddcda51e4baad3039dbb4fc4b4e1a2b8e16",
"md5": "2e6976e60d286f7df6d43fa9cc3abfc8",
"sha256": "b9b6c2e5280f7d54fa82c58fe09983f68c5b6f634ac3fa339f8ba16a5715cab7"
},
"downloads": -1,
"filename": "hacking-7.0.0.tar.gz",
"has_sig": false,
"md5_digest": "2e6976e60d286f7df6d43fa9cc3abfc8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 61165,
"upload_time": "2024-08-16T16:13:47",
"upload_time_iso_8601": "2024-08-16T16:13:47.939897Z",
"url": "https://files.pythonhosted.org/packages/f7/19/cf7a61cb63288c226bf2fa012ddcda51e4baad3039dbb4fc4b4e1a2b8e16/hacking-7.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-16 16:13:47",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "hacking"
}
JSON