flake8-elegant-objects 1.1.1__tar.gz → 2.0.0__tar.gz

{flake8_elegant_objects-1.1.1 → flake8_elegant_objects-2.0.0}/.github/workflows/lint.yml

@@ -6,6 +6,13 @@ on:
   pull_request:
     branches: [master, main]
 
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   lint:
     runs-on: ubuntu-latest

flake8_elegant_objects-2.0.0/.github/workflows/publish.yml

@@ -0,0 +1,87 @@
+name: Publish
+
+# Trusted publishing: PyPI verifies this workflow through OIDC and issues a
+# short-lived token, so no API token is stored anywhere. It requires a pending
+# publisher configured once at
+# https://pypi.org/manage/project/flake8-elegant-objects/settings/publishing/
+# naming this repository, this workflow file and the pypi environment.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: 'latest'
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.10
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run unit tests
+        run: uv run pytest tests/ -q
+
+      - name: Build package
+        run: uv build
+
+      - name: Check that the built version matches the tag
+        if: github.event_name == 'release'
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          built=$(ls dist/*.whl | sed -E 's/.*-([0-9]+\.[0-9]+\.[0-9]+)-py3.*/\1/')
+          if [ "$tag" != "$built" ]; then
+            echo "tag $tag does not match built version $built"
+            exit 1
+          fi
+
+      # The 1.1.1 release shipped a console script that raised ImportError.
+      # An editable install hides that, so the wheel is installed on its own
+      # and actually run before anything reaches PyPI.
+      - name: Run the wheel in a clean environment
+        run: |
+          uv venv /tmp/clean
+          uv pip install --python /tmp/clean/bin/python dist/*.whl flake8
+          printf 'from typing import final\n\n@final\nclass Money:\n    def __init__(self, cents):\n        self.cents = cents\n' > /tmp/clean_sample.py
+          /tmp/clean/bin/flake8-elegant-objects /tmp/clean_sample.py
+          /tmp/clean/bin/python -m flake8 --version | grep flake8-elegant-objects
+
+      - name: Upload distribution
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: pypi
+      url: https://pypi.org/p/flake8-elegant-objects
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distribution
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

flake8_elegant_objects-2.0.0/.github/workflows/test.yml

@@ -0,0 +1,92 @@
+name: Build and Test
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: 'latest'
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Check that the lockfile matches pyproject.toml
+        run: uv lock --check
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run unit tests
+        run: uv run pytest tests/ -v
+
+  package:
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: 'latest'
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.10
+
+      - name: Build package
+        run: uv build
+
+      # The 1.1.1 release shipped a console script that raised ImportError.
+      # An editable install hides that class of fault, so the built wheel is
+      # installed into an environment of its own and actually run.
+      - name: Install the built wheel into a clean environment
+        run: |
+          uv venv /tmp/clean
+          uv pip install --python /tmp/clean/bin/python dist/*.whl flake8
+
+      - name: Run the console script from the wheel
+        run: |
+          printf 'from typing import final\n\n@final\nclass Money:\n    def __init__(self, cents):\n        self.cents = cents\n' > /tmp/clean_sample.py
+          /tmp/clean/bin/flake8-elegant-objects /tmp/clean_sample.py
+
+      - name: Run the plugin through flake8 from the wheel
+        run: |
+          printf 'class Parser:\n    def parse(self, text):\n        return None\n' > /tmp/dirty_sample.py
+          /tmp/clean/bin/python -m flake8 --version | grep flake8-elegant-objects
+          if /tmp/clean/bin/python -m flake8 --select=EO /tmp/dirty_sample.py; then
+            echo "the plugin reported nothing on code that violates EO001"
+            exit 1
+          fi
+
+      - name: Upload distribution
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

{flake8_elegant_objects-1.1.1 → flake8_elegant_objects-2.0.0}/CHANGELOG.md

@@ -5,6 +5,87 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.0] - 2026-07-22
+
+Rules changed shape in ways that will report differently on code that passed
+1.1.1. Two codes are gone, one stopped enforcing something the principles do
+not ask for, and three started catching what they had been missing. Expect new
+findings on an unchanged codebase.
+
+### Removed
+
+- `EO022` (missing factory methods) and `EO024` (missing immutability enforcement).
+  Both prescribed a technique rather than forbidding one, neither appears in the
+  Elegant Objects principles, and both duplicated `EO016` on the same line.
+- Procedural verb detection in `EO002`/`EO003`/`EO004`. Methods are nouns or verbs
+  separated into queries and commands, so verb names are not violations. These codes
+  now report -er names only, as `EO001` always did.
+
+### Fixed
+
+- The `flake8-elegant-objects` console script raised `ImportError`: it pointed at
+  `flake8_elegant_objects:main`, while `main` lives in `__main__.py`.
+- `EO006` no longer reports a constructor docstring as code.
+- `EO005` now reports a bare `return` in a function that returns values elsewhere.
+- `EO009` now detects decorators reached through a module, such as
+  `@abc.abstractstaticmethod`.
+- `EO010` now detects `typing.cast`, `builtins.isinstance`, `issubclass`,
+  `match`/`case` class patterns, and reflection through `__class__`, `__bases__`,
+  `__mro__` and `__subclasses__`.
+- `EO007` now detects `@x.setter` methods, which are setters regardless of name.
+- `EO012` no longer reports a test docstring as a statement, and now requires the
+  single assertion to be the last statement of the method. The count was already
+  enforced; the position was not, so an assertion followed by anything permitted
+  passed. Its three faults now carry three distinct messages under the one code.
+- `EO001`-`EO004` now match the -er and -or suffixes themselves, including plurals,
+  instead of a closed list of about seventy words. The principle says "readers,
+  parsers, controllers, sorters, and so on", and the old list missed Iterator,
+  Visitor, Simulator, Handlers and everything else outside it. Ordinary nouns are
+  allowed by their final word, so ImmutableUser and TaskCounter still pass.
+
+### Added
+
+- `EO028`: a class that is not final invites implementation inheritance. Protocols,
+  abstract base classes and test suites are exempt, since they exist to be extended.
+- `EO029`: a class holding more than four attributes has stopped being one object.
+- `EO009` now covers module level functions, which are the Python static method.
+- `EO007` now covers `@property` accessors whose body is a single `return self._x`.
+- `EO011` now covers `async` methods, and exempts test methods, which implement
+  no contract.
+- Tests for the standalone CLI and for plugin registration through flake8 itself,
+  neither of which was covered before.
+- `flake8` as a development dependency.
+- A self check: the plugin runs over its own source and fails when any violation
+  count grows or a new code starts firing. The counts are debt, not a target.
+- A check that the version flake8 reports matches the one the distribution
+  declares. The two were written out independently in `pyproject.toml` and
+  `__init__.py`.
+- A coverage floor of 90 percent, which the README badge had been claiming
+  without anything enforcing it.
+
+### Changed
+
+- The plugin obeys every rule it enforces. What began as 300 violations against
+  its own source is 0, with 23 suppressions that each name a reason: entry point
+  signatures flake8 and pyproject dictate, one isinstance inside `Instance`, one
+  `None` for the absence of an enclosing class, `Generic` for TypeGuard narrowing,
+  and helper methods whose contracts would mean a Protocol apiece. A test fixes
+  that count, so a new suppression has to be taken deliberately.
+- Type discrimination lives in one object. `Instance(kind).covers(node)` replaced
+  148 direct `isinstance` calls across nineteen files; its answer is a `TypeGuard`,
+  so callers keep the narrowing they had.
+- Error messages moved from the `ErrorCodes` class to module constants, and the
+  parent of a node is a real map rather than an attribute stitched onto borrowed
+  ast objects.
+
+- CI installs the built wheel into a clean environment and runs the console
+  script and `flake8 --select=EO` from it. Editable installs hide the fault
+  that shipped in 1.1.1.
+- CI checks the lockfile against `pyproject.toml`, tests Python 3.14, caches uv,
+  cancels superseded runs and restricts token permissions to reading contents.
+- Linting, formatting and type checking no longer run in both workflows. They
+  ran four times per push, once per Python version, and now run once.
+
 ## [1.1.1] - 2024-06-30
 
 ### Minor release

flake8_elegant_objects-2.0.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: flake8-elegant-objects
+Version: 2.0.0
+Summary: Flake8 plugin enforcing Elegant Objects principles: no -er naming, no null, no getters/setters, immutable objects
+Project-URL: Homepage, https://github.com/AntonProkopyev/flake8-elegant-objects
+Project-URL: Repository, https://github.com/AntonProkopyev/flake8-elegant-objects.git
+Project-URL: Issues, https://github.com/AntonProkopyev/flake8-elegant-objects/issues
+Project-URL: Documentation, https://github.com/AntonProkopyev/flake8-elegant-objects#readme
+Author: Anton Prokopyev
+License: MIT
+License-File: LICENSE
+Keywords: code-quality,elegant-objects,flake8,linting,object-oriented,python,static-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: Flake8
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# flake8-elegant-objects
+
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](https://github.com/AntonProkopyev/flake8-elegant-objects)
+[![Coverage](https://img.shields.io/badge/coverage-94%25-brightgreen.svg)](https://github.com/AntonProkopyev/flake8-elegant-objects)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://python.org)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![EO principles respected here](https://www.elegantobjects.org/badge.svg)](https://www.elegantobjects.org)
+
+A flake8 plugin that checks Python against the
+[Elegant Objects](https://www.elegantobjects.org/) principles: no null, no code
+in constructors, no getters and setters, no mutable objects, no -er names, no
+static methods, no type discrimination, no public methods without a contract,
+no statements in tests beyond the assertion, no ORM, no implementation
+inheritance.
+
+Every message ends with a link to the article the rule comes from, so a code
+you have not met before explains itself.
+
+## Install
+
+```bash
+pip install flake8-elegant-objects
+```
+
+## Run
+
+Through flake8, which is how most projects will want it:
+
+```bash
+flake8 --select=EO your_package/
+```
+
+The plugin registers itself on install; `--select=EO` narrows the run to its
+codes. Individual codes work too, and so does `# noqa: EO001`.
+
+Standalone, when you want it without flake8:
+
+```bash
+python -m flake8_elegant_objects your_package/*.py
+flake8-elegant-objects --show-source your_package/*.py
+```
+
+Both forms honour `noqa` comments and report the same violations.
+
+## Codes
+
+**Naming.** The principle names "readers, parsers, controllers, sorters, and so
+on", so the -er and -or suffixes are matched rather than a fixed list of words.
+Ordinary nouns are allowed by their final word: `ImmutableUser` and
+`TaskCounter` pass, `Formatter` and `Recorder` do not.
+
+| | |
+|---|---|
+| `EO001` | class name ends in -er |
+| `EO002` | method name ends in -er |
+| `EO003` | variable name ends in -er |
+| `EO004` | function name ends in -er |
+
+Verb names are not violations. A method is a noun that builds or a verb that
+commands, and the principle objects to actors, not to verbs.
+
+**Objects.**
+
+| | |
+|---|---|
+| `EO005` | null used, including a bare `return` beside returns that carry a value |
+| `EO006` | a constructor doing anything beyond binding its parameters |
+| `EO007` | a getter or setter, whether spelled `get_name` or `@property` |
+| `EO009` | a static method, a class method, or a module level function |
+| `EO010` | `isinstance`, `type`, `cast`, reflection, or a `match` on classes |
+| `EO011` | a public method with no Protocol or ABC behind it |
+| `EO012` | a test holding anything but one assertion, closing with it |
+| `EO013` | an ORM or ActiveRecord call |
+| `EO014` | inheritance from something that is not a contract |
+| `EO028` | a class left open, which invites implementation inheritance |
+| `EO029` | a class holding more than four attributes |
+
+**Mutability.** One principle, several shapes.
+
+| | |
+|---|---|
+| `EO008` | a dataclass that is not frozen |
+| `EO015` | a mutable class attribute |
+| `EO016` | a mutable instance attribute |
+| `EO017` | an instance attribute assigned outside the constructor |
+| `EO018` | an augmented assignment to an attribute |
+| `EO019` | a call that mutates in place, such as `append` |
+| `EO020` | a subscript assignment to an attribute |
+| `EO021` | a mutation reached through a chain |
+| `EO023` | a mutable default argument |
+| `EO025` | a method that mutates where it could return a new instance |
+| `EO026` | internal mutable state handed out |
+| `EO027` | a mutable argument stored without a copy |
+
+## Where this is stricter or looser than the principles
+
+`EO002`, `EO003` and `EO004` extend a rule about class names to methods,
+variables and functions. `EO028` and `EO029` are not on elegantobjects.org at
+all; they come from the
+[rules yegor256 gives his own agents](https://github.com/yegor256/prompt).
+
+`EO011` and `EO014` do not judge a base class they cannot see. A Protocol
+declared in one module and implemented in another is ordinary, and a plugin
+reading one file at a time has no evidence about an imported name. A base
+defined in the file and not a contract is still reported.
+
+`EO012` allows a bare `assert` and `self.assertEqual`, because Python has no
+Hamcrest and `assertThat` would be a foreign requirement.
+
+Test methods are exempt from `EO011`: they implement no contract.
+
+## The plugin on itself
+
+It passes. Run it over its own source and nothing is reported that is not
+marked, and each mark says why:
+
+- `EO009` and `EO010` where flake8 and `pyproject.toml` dictate a signature
+- `EO010` once inside `Instance`, the object every type check goes through,
+  because a linter reading syntax trees cannot ask a node what it is any other
+  way
+- `EO005` once, for the absence of an enclosing class, where a null object
+  would answer with lies rather than with nothing
+- `EO011` on helper methods whose contracts would cost a Protocol apiece
+- `EO014` on `Generic`, which is what keeps type narrowing alive
+
+`tests/test_self_check.py` fixes that count, so a new suppression has to be
+argued for rather than added in passing.
+
+## Configure
+
+```ini
+[flake8]
+select = E,W,F,EO
+per-file-ignores =
+    tests/*:EO011,EO012
+```
+
+If you use ruff alongside, tell it these codes belong to someone else, or it
+will strip the `noqa` comments that name them:
+
+```toml
+[tool.ruff.lint]
+external = ["EO"]
+```
+
+## Develop
+
+```bash
+uv sync
+uv run pytest tests/
+uv run ruff check . && uv run ruff format --check .
+uv run mypy .
+```
+
+### Layout
+
+```
+flake8_elegant_objects/
+├── __init__.py                  # the flake8 plugin
+├── __main__.py                  # the standalone command
+├── base.py                      # Instance, Source, Violation, messages
+├── links.py                     # the article behind each code
+├── noqa.py                      # suppression comments outside flake8
+├── no_constructor_code.py       # EO006
+├── no_er_name.py                # EO001-EO004
+├── no_getters_setters.py        # EO007
+├── no_implementation_inheritance.py  # EO014
+├── no_impure_tests.py           # EO012
+├── no_null.py                   # EO005
+├── no_open_classes.py           # EO028, EO029
+├── no_orm.py                    # EO013
+├── no_public_methods_without_contracts.py  # EO011
+├── no_static.py                 # EO009
+├── no_type_discrimination.py    # EO010
+└── no_mutable_objects/          # EO008, EO015-EO027
+    ├── base.py                  # what counts as mutable
+    ├── core.py                  # the orchestrator
+    ├── copy_on_write_checker.py # EO025
+    ├── deep_checker.py          # mutations across a class
+    ├── pattern_detectors.py     # EO026, EO027
+    └── shared_state_checker.py  # shared mutable state
+```
+
+## Reading
+
+- [Elegant Objects](https://www.elegantobjects.org/), the principles themselves
+- [Object Thinking](http://amzn.to/2BVeiNl) by David West
+- [Elegant Objects](http://www.yegor256.com/elegant-objects.html) vol. 1 and 2
+  by Yegor Bugayenko
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).