Add requirements.txt, update README.md with "pip install -r requirements"

[balintkissdev]

Providing a requirements.txt makes sure packages will have the same versions across all machines to avoid breakage due to dependency hell and also allows installing them with a pip install -r requirements.txt one-liner instead of having the user manually track down the packages or typing pip install docopt validators python-dateutils pytest.

I find it especially useful in sandboxed environments created with virtualenv. That way people can install packages locally to the project without polluting their system with global packages.

[OliverCi]

Hi @balintkissdev,

adding a requirements.txt is a good idea. Some questions:

• It references several packages, which are not used by the current code (iniconfig, packaging, ...). Was there a certain reason for this?
• It requires exact versions (e.g. pytest==7.4.2). Was this just because the file was generated? I might be better to stay flexible by omitting version numbers or only require minimum versions (>=), if we know it is needed for compatibility.

[balintkissdev]

The requirements.txt was generated using pip freeze > requirements.txt.

It references several packages, which are not used by the current code (iniconfig, packaging, ...). Was there a certain reason for this?

Those extra packages are dependencies for python-dateutil and pytest.

• iniconfig is required by pytest
• packaging is required by pytest
• pluggy is required by pytest
• six is required by python-dateutil

It requires exact versions (e.g. pytest==7.4.2). Was this just because the file was generated? I might be better to stay flexible by omitting version numbers or only require minimum versions (>=), if we know it is needed for compatibility.

Yes, it is due to generation by pip freeze. The reason Python maintainers make versions of both installed packages and their dependencies fixed is to avoid cases where a package that contains a breaking change is silently upgraded on the user's environment (with >= even major versions of packages are updated), leading to dependency hell.

An elegant solution to avoid installing breaking major version changes is fixing the versions to only install patch and minor version updates. There is the ~= syntax which means "Install only compatible packages". I changed my requirements.txt to

docopt~=0.6
pytest~=7.0
python_dateutil~=2.0
validators~=0.0

and it managed to install the packages with the latest patch/minor versions and their dependencies:

Collecting docopt~=0.6 (from -r requirements.txt (line 1))
  Using cached docopt-0.6.2-py2.py3-none-any.whl
Collecting pytest~=7.0 (from -r requirements.txt (line 2))
  Obtaining dependency information for pytest~=7.0 from https://files.pythonhosted.org/packages/df/d0/e192c4275aecabf74faa1aacd75ef700091913236ec78b1a98f62a2412ee/pytest-7.4.2-py3-none-any.whl.metadata
  Using cached pytest-7.4.2-py3-none-any.whl.metadata (7.9 kB)
Collecting python_dateutil~=2.0 (from -r requirements.txt (line 3))
  Using cached python_dateutil-2.8.2-py2.py3-none-any.whl (247 kB)
Collecting validators~=0.0 (from -r requirements.txt (line 4))
  Obtaining dependency information for validators~=0.0 from https://files.pythonhosted.org/packages/3a/0c/785d317eea99c3739821718f118c70537639aa43f96bfa1d83a71f68eaf6/validators-0.22.0-py3-none-any.whl.metadata
  Using cached validators-0.22.0-py3-none-any.whl.metadata (4.7 kB)
Collecting iniconfig (from pytest~=7.0->-r requirements.txt (line 2))
  Using cached iniconfig-2.0.0-py3-none-any.whl (5.9 kB)
Collecting packaging (from pytest~=7.0->-r requirements.txt (line 2))
  Using cached packaging-23.1-py3-none-any.whl (48 kB)
Collecting pluggy<2.0,>=0.12 (from pytest~=7.0->-r requirements.txt (line 2))
  Obtaining dependency information for pluggy<2.0,>=0.12 from https://files.pythonhosted.org/packages/05/b8/42ed91898d4784546c5f06c60506400548db3f7a4b3fb441cba4e5c17952/pluggy-1.3.0-py3-none-any.whl.metadata
  Using cached pluggy-1.3.0-py3-none-any.whl.metadata (4.3 kB)
Collecting six>=1.5 (from python_dateutil~=2.0->-r requirements.txt (line 3))
  Using cached six-1.16.0-py2.py3-none-any.whl (11 kB)
Using cached pytest-7.4.2-py3-none-any.whl (324 kB)
Using cached validators-0.22.0-py3-none-any.whl (26 kB)
Using cached pluggy-1.3.0-py3-none-any.whl (18 kB)
Installing collected packages: docopt, validators, six, pluggy, packaging, iniconfig, python_dateutil, pytest
Successfully installed docopt-0.6.2 iniconfig-2.0.0 packaging-23.1 pluggy-1.3.0 pytest-7.4.2 python_dateutil-2.8.2 six-1.16.0 validators-0.22.0

I am more okay with this approach instead of >=.