Outdated build instructions in README

[cuu508]

I followed the instructions in the "BUILDING" section in README:

git clone git@github.com:aio-libs/aiosmtpd.git
python3 -m venv .venv
source .venv/bin/activate
python setup.py install

This produces:

Traceback (most recent call last):
  File "/tmp/aiosmtpd/setup.py", line 1, in <module>
    from setuptools import setup
ModuleNotFoundError: No module named 'setuptools'

Is there perhaps an instruction missing there?

I'm using Ubuntu 24.04 and system's default python, python 3.12.3.

[cuu508]

I then tried to run the test suite. I installed and ran tox:

pip install tox
tox

This produces long output with various error messages. Here's the trailing part of it:

[...]
housekeep.py:205:37: ANN204 Missing return type annotation for special method
housekeep.py:210:22: ANN101 Missing type annotation for self in method
housekeep.py:210:29: ANN002 Missing type annotation for *args
housekeep.py:210:37: ANN003 Missing type annotation for **kwargs
housekeep.py:210:44: ANN204 Missing return type annotation for special method
housekeep.py:245:28: ANN201 Missing return type annotation for public function
qa: exit 1 (4.91 seconds) /tmp/aiosmtpd> python -m flake8 aiosmtpd setup.py housekeep.py release.py pid=2275641
static: skipped because platform linux does not match ^(?!win32)(?!cygwin)
qa: FAIL ✖ in 14.98 seconds
static: SKIP ⚠ in 0 seconds
docs: failed with Could not open requirements file /tmp/aiosmtpd/aiosmtpd/docs/RTD-requirements.txt: [Errno 2] No such file or directory: '/tmp/aiosmtpd/aiosmtpd/docs/RTD-requirements.txt' for tox env py within deps
docs: FAIL ✖ in 0.05 seconds
py38-nocov: skipped because could not find python interpreter with spec(s): py38
py38-nocov: SKIP ⚠ in 0 seconds
py38-cov: skipped because could not find python interpreter with spec(s): py38
py38-cov: SKIP ⚠ in 0 seconds
py38-diffcov: skipped because could not find python interpreter with spec(s): py38
py38-diffcov: SKIP ⚠ in 0 seconds
py39-nocov: skipped because could not find python interpreter with spec(s): py39
py39-nocov: SKIP ⚠ in 0 seconds
py39-cov: skipped because could not find python interpreter with spec(s): py39
py39-cov: SKIP ⚠ in 0 seconds
py39-diffcov: skipped because could not find python interpreter with spec(s): py39
py39-diffcov: SKIP ⚠ in 0 seconds
py310-nocov: skipped because could not find python interpreter with spec(s): py310
py310-nocov: SKIP ⚠ in 0 seconds
py310-cov: skipped because could not find python interpreter with spec(s): py310
py310-cov: SKIP ⚠ in 0 seconds
py310-diffcov: skipped because could not find python interpreter with spec(s): py310
py311-nocov: skipped because could not find python interpreter with spec(s): py311
py310-diffcov: SKIP ⚠ in 0 seconds
py311-nocov: SKIP ⚠ in 0 seconds
py311-cov: skipped because could not find python interpreter with spec(s): py311
py311-cov: SKIP ⚠ in 0 seconds
py311-diffcov: skipped because could not find python interpreter with spec(s): py311
py311-diffcov: SKIP ⚠ in 0 seconds
py312-nocov: install_deps> python -I -m pip install bandit colorama packaging py pytest-mock pytest-print pytest-profiling pytest-sugar 'pytest>=6.0'
py312-nocov: install_package_deps> python -I -m pip install atpublic attrs
py312-nocov: install_package> python -I -m pip install --force-reinstall --no-deps /tmp/aiosmtpd/.tox/.tmp/package/2/aiosmtpd-1.4.6-0.editable-py3-none-any.whl
py312-nocov: commands[0]> python housekeep.py prep
▞▞▞ Python interpreter details:
    3.12.3 (main, Feb  4 2025, 14:48:35) [GCC 13.3.0]
    /tmp/aiosmtpd/.tox/py312-nocov/bin/python
>>> housekeep.py prep
py312-nocov: commands[1]> bandit -c bandit.yml -r aiosmtpd
[main]	INFO	profile include tests: None
[main]	INFO	profile exclude tests: B404,B101
[main]	INFO	cli include tests: None
[main]	INFO	cli exclude tests: None
[main]	INFO	using config: bandit.yml
[main]	INFO	running on Python 3.12.3
Run started:2025-03-10 08:11:49.853407

Test results:
	No issues identified.

Code scanned:
	Total lines of code: 8157
	Total lines skipped (#nosec): 3

Run metrics:
	Total issues (by severity):
		Undefined: 0
		Low: 0
		Medium: 0
		High: 0
	Total issues (by confidence):
		Undefined: 0
		Low: 0
		Medium: 0
		High: 0
Files skipped (0):
py312-nocov: commands[2]> pytest --verbose -p no:cov --tb=short
ERROR: usage: pytest [options] [file_or_dir] [file_or_dir] [...]
pytest: error: unrecognized arguments: --cov=aiosmtpd/ --cov-report
  inifile: /tmp/aiosmtpd/pytest.ini
  rootdir: /tmp/aiosmtpd

py312-nocov: exit 4 (0.19 seconds) /tmp/aiosmtpd> pytest --verbose -p no:cov --tb=short pid=2276006
py312-nocov: FAIL ✖ in 6.38 seconds
py312-cov: install_deps> python -I -m pip install bandit colorama coverage-conditional-plugin 'coverage>=7.0.1' 'coverage[toml]' packaging py pytest-cov pytest-mock pytest-print pytest-profiling pytest-sugar 'pytest>=6.0'
py312-cov: install_package_deps> python -I -m pip install atpublic attrs
py312-cov: install_package> python -I -m pip install --force-reinstall --no-deps /tmp/aiosmtpd/.tox/.tmp/package/3/aiosmtpd-1.4.6-0.editable-py3-none-any.whl
py312-cov: commands[0]> python housekeep.py prep
▞▞▞ Python interpreter details:
    3.12.3 (main, Feb  4 2025, 14:48:35) [GCC 13.3.0]
    /tmp/aiosmtpd/.tox/py312-cov/bin/python
>>> housekeep.py prep
py312-cov: commands[1]> bandit -c bandit.yml -r aiosmtpd
[main]	INFO	profile include tests: None
[main]	INFO	profile exclude tests: B404,B101
[main]	INFO	cli include tests: None
[main]	INFO	cli exclude tests: None
[main]	INFO	using config: bandit.yml
[main]	INFO	running on Python 3.12.3
Run started:2025-03-10 08:11:56.700653

Test results:
	No issues identified.

Code scanned:
	Total lines of code: 8157
	Total lines skipped (#nosec): 3

Run metrics:
	Total issues (by severity):
		Undefined: 0
		Low: 0
		Medium: 0
		High: 0
	Total issues (by confidence):
		Undefined: 0
		Low: 0
		Medium: 0
		High: 0
Files skipped (0):
py312-cov: commands[2]> pytest --cov --cov-report=xml --cov-report=html --cov-report=term --tb=short
Test session starts (platform: linux, Python 3.12.3, pytest 8.3.5, pytest-sugar 1.0.0)
cachedir: .tox/py312-cov/.pytest_cache
rootdir: /tmp/aiosmtpd
configfile: pytest.ini
testpaths: aiosmtpd/tests/, aiosmtpd/qa/
plugins: mock-3.14.0, profiling-1.8.1, print-1.1.0, sugar-1.0.0, cov-6.0.0
collected 566 items                                                                                                                                                                                                                                          
INTERNALERROR> Traceback (most recent call last):
INTERNALERROR>   File "/tmp/aiosmtpd/.tox/py312-cov/lib/python3.12/site-packages/_pytest/main.py", line 283, in wrap_session
INTERNALERROR>     session.exitstatus = doit(config, session) or 0
INTERNALERROR>                          ^^^^^^^^^^^^^^^^^^^^^
INTERNALERROR>   File "/tmp/aiosmtpd/.tox/py312-cov/lib/python3.12/site-packages/_pytest/main.py", line 336, in _main
INTERNALERROR>     config.hook.pytest_collection(session=session)
INTERNALERROR>   File "/tmp/aiosmtpd/.tox/py312-cov/lib/python3.12/site-packages/pluggy/_hooks.py", line 513, in __call__
INTERNALERROR>     return self._hookexec(self.name, self._hookimpls.copy(), kwargs, firstresult)
INTERNALERROR>            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
INTERNALERROR>   File "/tmp/aiosmtpd/.tox/py312-cov/lib/python3.12/site-packages/pluggy/_manager.py", line 120, in _hookexec
INTERNALERROR>     return self._inner_hookexec(hook_name, methods, kwargs, firstresult)
INTERNALERROR>            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
INTERNALERROR>   File "/tmp/aiosmtpd/.tox/py312-cov/lib/python3.12/site-packages/pluggy/_callers.py", line 139, in _multicall
INTERNALERROR>     raise exception.with_traceback(exception.__traceback__)
INTERNALERROR>   File "/tmp/aiosmtpd/.tox/py312-cov/lib/python3.12/site-packages/pluggy/_callers.py", line 122, in _multicall
INTERNALERROR>     teardown.throw(exception)  # type: ignore[union-attr]
INTERNALERROR>     ^^^^^^^^^^^^^^^^^^^^^^^^^
INTERNALERROR>   File "/tmp/aiosmtpd/.tox/py312-cov/lib/python3.12/site-packages/_pytest/logging.py", line 790, in pytest_collection
INTERNALERROR>     return (yield)
INTERNALERROR>             ^^^^^
INTERNALERROR>   File "/tmp/aiosmtpd/.tox/py312-cov/lib/python3.12/site-packages/pluggy/_callers.py", line 122, in _multicall
INTERNALERROR>     teardown.throw(exception)  # type: ignore[union-attr]
INTERNALERROR>     ^^^^^^^^^^^^^^^^^^^^^^^^^
INTERNALERROR>   File "/tmp/aiosmtpd/.tox/py312-cov/lib/python3.12/site-packages/_pytest/warnings.py", line 121, in pytest_collection
INTERNALERROR>     return (yield)
INTERNALERROR>             ^^^^^
INTERNALERROR>   File "/tmp/aiosmtpd/.tox/py312-cov/lib/python3.12/site-packages/pluggy/_callers.py", line 124, in _multicall
INTERNALERROR>     teardown.send(result)  # type: ignore[union-attr]
INTERNALERROR>     ^^^^^^^^^^^^^^^^^^^^^
INTERNALERROR>   File "/tmp/aiosmtpd/.tox/py312-cov/lib/python3.12/site-packages/_pytest/config/__init__.py", line 1419, in pytest_collection
INTERNALERROR>     self._validate_config_options()
INTERNALERROR>   File "/tmp/aiosmtpd/.tox/py312-cov/lib/python3.12/site-packages/_pytest/config/__init__.py", line 1441, in _validate_config_options
INTERNALERROR>     self._warn_or_fail_if_strict(f"Unknown config option: {key}\n")
INTERNALERROR>   File "/tmp/aiosmtpd/.tox/py312-cov/lib/python3.12/site-packages/_pytest/config/__init__.py", line 1480, in _warn_or_fail_if_strict
INTERNALERROR>     self.issue_config_time_warning(PytestConfigWarning(message), stacklevel=3)
INTERNALERROR>   File "/tmp/aiosmtpd/.tox/py312-cov/lib/python3.12/site-packages/_pytest/config/__init__.py", line 1532, in issue_config_time_warning
INTERNALERROR>     warnings.warn(warning, stacklevel=stacklevel)
INTERNALERROR> pytest.PytestConfigWarning: Unknown config option: asyncio_mode


Results (0.96s):
py312-cov: exit 3 (1.45 seconds) /tmp/aiosmtpd> pytest --cov --cov-report=xml --cov-report=html --cov-report=term --tb=short pid=2276122
py312-cov: FAIL ✖ in 8.11 seconds
py312-diffcov: install_deps> python -I -m pip install bandit colorama coverage-conditional-plugin 'coverage>=7.0.1' 'coverage[toml]' diff_cover packaging py pytest-cov pytest-mock pytest-print pytest-profiling pytest-sugar 'pytest>=6.0'
py312-diffcov: install_package_deps> python -I -m pip install atpublic attrs
py312-diffcov: install_package> python -I -m pip install --force-reinstall --no-deps /tmp/aiosmtpd/.tox/.tmp/package/4/aiosmtpd-1.4.6-0.editable-py3-none-any.whl
py312-diffcov: commands[0]> python housekeep.py prep
▞▞▞ Python interpreter details:
    3.12.3 (main, Feb  4 2025, 14:48:35) [GCC 13.3.0]
    /tmp/aiosmtpd/.tox/py312-diffcov/bin/python
>>> housekeep.py prep
py312-diffcov: commands[1]> diff-cover _dump/coverage-py312.xml --html-report htmlcov/diffcov-py312.html
Traceback (most recent call last):
  File "/tmp/aiosmtpd/.tox/py312-diffcov/bin/diff-cover", line 8, in <module>
    sys.exit(main())
             ^^^^^^
  File "/tmp/aiosmtpd/.tox/py312-diffcov/lib/python3.12/site-packages/diff_cover/diff_cover_tool.py", line 307, in main
    percent_covered = generate_coverage_report(
                      ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/aiosmtpd/.tox/py312-diffcov/lib/python3.12/site-packages/diff_cover/diff_cover_tool.py", line 234, in generate_coverage_report
    etree.parse(coverage_file)
  File "/usr/lib/python3.12/xml/etree/ElementTree.py", line 1204, in parse
    tree.parse(source, parser)
  File "/usr/lib/python3.12/xml/etree/ElementTree.py", line 558, in parse
    source = open(source, "rb")
             ^^^^^^^^^^^^^^^^^^
FileNotFoundError: [Errno 2] No such file or directory: '_dump/coverage-py312.xml'
py312-diffcov: exit 1 (0.12 seconds) /tmp/aiosmtpd> diff-cover _dump/coverage-py312.xml --html-report htmlcov/diffcov-py312.html pid=2276244
py312-diffcov: FAIL ✖ in 6.45 seconds
pypy3-nocov: skipped because could not find python interpreter with spec(s): pypy3
pypy3-nocov: SKIP ⚠ in 0 seconds
pypy3-cov: skipped because could not find python interpreter with spec(s): pypy3
pypy3-diffcov: skipped because could not find python interpreter with spec(s): pypy3
pypy3-cov: SKIP ⚠ in 0 seconds
  qa: FAIL code 1 (14.98=setup[9.86]+cmd[0.05,0.16,4.91] seconds)
  static: SKIP (0.00 seconds)
  docs: FAIL code 1 (0.05 seconds)
  py38-nocov: SKIP (0.00 seconds)
  py38-cov: SKIP (0.00 seconds)
  py38-diffcov: SKIP (0.00 seconds)
  py39-nocov: SKIP (0.00 seconds)
  py39-cov: SKIP (0.00 seconds)
  py39-diffcov: SKIP (0.00 seconds)
  py310-nocov: SKIP (0.00 seconds)
  py310-cov: SKIP (0.00 seconds)
  py310-diffcov: SKIP (0.00 seconds)
  py311-nocov: SKIP (0.00 seconds)
  py311-cov: SKIP (0.00 seconds)
  py311-diffcov: SKIP (0.00 seconds)
  py312-nocov: FAIL code 4 (6.38=setup[5.32]+cmd[0.04,0.82,0.19] seconds)
  py312-cov: FAIL code 3 (8.11=setup[5.80]+cmd[0.05,0.81,1.45] seconds)
  py312-diffcov: FAIL code 1 (6.45=setup[6.28]+cmd[0.05,0.12] seconds)
  pypy3-nocov: SKIP (0.00 seconds)
  pypy3-cov: SKIP (0.00 seconds)
  pypy3-diffcov: SKIP (0.00 seconds)
  evaluation failed :( (36.53 seconds)

Is the test suite currently broken or am I running it incorrectly?

[webknjaz]

The CI doesn't use tox at the moment (would be great to fix that!)

For now, just follow what's in the GHA workflow definition.