Update Dependency Policy (#2958)

.github/dependabot.yml

@@ -0,0 +1,14 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "friday"
+
+  # Updates the dependencies of the GitHub Actions workflows
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+      day: "friday"

.github/workflows/test.yml

@@ -6,6 +6,9 @@ on:
   push:
     branches: 
       - master
+  schedule:
+    # Run monday and friday morning at 03:07 - odd time to spread load on GitHub Actions
+    - cron: '7 3 * * 1,5'
 
 jobs:
   pytest:

.pre-commit-config.yaml

@@ -25,10 +25,10 @@ repos:
           #  run pylint across multiple cpu cores to speed it up-
           - --jobs=0  # See https://pylint.pycqa.org/en/latest/user_guide/run.html?#parallel-execution to know more
         additional_dependencies:
-          - httpx >= 0.20.0,<1.0
-          - tornado>=6.1
-          - APScheduler==3.6.3
-          - cachetools==4.2.2
+          - httpx~=0.22.0
+          - tornado~=6.1
+          - APScheduler~=3.9.1
+          - cachetools~=5.0.0
           - . # this basically does `pip install -e .`
 -   repo: https://github.com/pre-commit/mirrors-mypy
     rev: v0.910
@@ -41,10 +41,10 @@ repos:
           - types-pytz
           - types-cryptography
           - types-cachetools
-          - httpx >= 0.20.0,<1.0
-          - tornado>=6.1
-          - APScheduler==3.6.3
-          - cachetools==4.2.2
+          - httpx~=0.22.0
+          - tornado~=6.1
+          - APScheduler~=3.9.1
+          - cachetools~=5.0.0
           - . # this basically does `pip install -e .`
     - id: mypy
       name: mypy-examples
@@ -53,10 +53,9 @@ repos:
         - --no-strict-optional
         - --follow-imports=silent
       additional_dependencies:
-        - certifi
-        - tornado>=6.1
-        - APScheduler==3.6.3
-        - cachetools==4.2.2
+        - tornado~=6.1
+        - APScheduler~=3.9.1
+        - cachetools~=5.0.0
         - . # this basically does `pip install -e .`
 -   repo: https://github.com/asottile/pyupgrade
     rev: v2.29.0

README.rst

@@ -145,15 +145,33 @@ Or you can install from source with:
     $ cd python-telegram-bot
     $ python setup.py install
 
+-----------------------------
+Dependencies & Their Versions
+-----------------------------
+
+``python-telegram-bot`` tries to use as few 3rd party dependencies as possible.
+However, for some features using a 3rd party library is more sane than implementing the functionality again.
+The dependencies are:
+
+* `httpx ~= 0.22.0 <https://www.python-httpx.org>`_ for ``telegram.request.HTTPXRequest``, the default networking backend
+* `tornado~=6.1 <https://www.tornadoweb.org/en/stable/>`_ for ``telegram.ext.Updater.start_webhook``
+* `cachetools~=5.0.0 <https://cachetools.readthedocs.io/en/latest/>`_ for ``telegram.ext.CallbackDataCache``
+* `APScheduler~=3.9.1 <https://apscheduler.readthedocs.io/en/3.x/>`_ for ``telegram.ext.JobQueue``
+
+``python-telegram-bot`` is most useful when used along with additional libraries.
+To minimize dependency conflicts, we try to be liberal in terms of version requirements on the dependencies.
+On the other hand, we have to ensure stability of ``python-telegram-bot``, which is why we do apply version bounds.
+If you encounter dependency conflicts due to these bounds, feel free to reach out.
+
 ---------------------
 Optional Dependencies
 ---------------------
 
 PTB can be installed with optional dependencies:
 
-* ``pip install python-telegram-bot[passport]`` installs the `cryptography <https://cryptography.io>`_ library. Use this, if you want to use Telegram Passport related functionality.
-* ``pip install python-telegram-bot[json]`` installs the `ujson <https://pypi.org/project/ujson/>`_ library. It will then be used for JSON de- & encoding, which can bring speed up compared to the standard `json <https://docs.python.org/3/library/json.html>`_ library.
-* ``pip install python-telegram-bot[socks]`` installs the `PySocks <https://pypi.org/project/PySocks/>`_ library. Use this, if you want to work behind a Socks5 server.
+* ``pip install python-telegram-bot[passport]`` installs the `cryptography>=3.0 <https://cryptography.io>`_ library. Use this, if you want to use Telegram Passport related functionality.
+* ``pip install python-telegram-bot[json]`` installs the `ujson>=4.0.0 <https://pypi.org/project/ujson/>`_ library. It will then be used for JSON de- & encoding, which can bring speed up compared to the standard `json <https://docs.python.org/3/library/json.html>`_ library.
+* ``pip install python-telegram-bot[socks]`` installs ``httpx[socks]``. Use this, if you want to work behind a Socks5 server.
 
 ===============
 Getting started

README_RAW.rst

@@ -138,14 +138,29 @@ Note
 
 Installing the `.tar.gz` archive available on PyPi directly via `pip` will *not* work as expected, as `pip` does not recognize that it should use `setup-raw.py` instead of `setup.py`.
 
+-----------------------------
+Dependencies & Their Versions
+-----------------------------
+
+``python-telegram-bot`` tries to use as few 3rd party dependencies as possible.
+However, for some features using a 3rd party library is more sane than implementing the functionality again.
+The dependencies are:
+
+* `httpx ~= 0.22.0 <https://www.python-httpx.org>`_ for ``telegram.request.HTTPXRequest``, the default networking backend
+
+``python-telegram-bot`` is most useful when used along with additional libraries.
+To minimize dependency conflicts, we try to be liberal in terms of version requirements on the dependencies.
+On the other hand, we have to ensure stability of ``python-telegram-bot``, which is why we do apply version bounds.
+If you encounter dependency conflicts due to these bounds, feel free to reach out.
+
 ---------------------
 Optional Dependencies
 ---------------------
 
 PTB can be installed with optional dependencies:
 
-* ``pip install python-telegram-bot-raw[passport]`` installs the `cryptography <https://cryptography.io>`_ library. Use this, if you want to use Telegram Passport related functionality.
-* ``pip install python-telegram-bot-raw[json]`` installs the `ujson <https://pypi.org/project/ujson/>`_ library. It will then be used for JSON de- & encoding, which can bring speed up compared to the standard `json <https://docs.python.org/3/library/json.html>`_ library.
+* ``pip install python-telegram-bot-raw[passport]`` installs the `cryptography>=3.0 <https://cryptography.io>`_ library. Use this, if you want to use Telegram Passport related functionality.
+* ``pip install python-telegram-bot-raw[json]`` installs the `ujson>=4.0.0 <https://pypi.org/project/ujson/>`_ library. It will then be used for JSON de- & encoding, which can bring speed up compared to the standard `json <https://docs.python.org/3/library/json.html>`_ library.
 
 ===============
 Getting started

requirements.txt

@@ -1,8 +1,21 @@
 # Make sure to install those as additional_dependencies in the
 # pre-commit hooks for pylint & mypy
+# Also update the readme accordingly
+
+# When dependencies release new versions and tests succeed, we should try to expand the allowed
+# versions and only increase the lower bound if necessary
+
+# httpx has no stable release yet, so let's be cautious for now
 httpx ~= 0.22.0
 # only telegram.ext: # Keep this line here; used in setup(-raw).py
-tornado>=6.1
-APScheduler==3.8.1
+
+# tornado is rather stable, but let's not allow the next mayor release without prior testing
+tornado~=6.1
+
+# Cachetools and APS don't have a strict stability policy.
+# Let's be cautious for now.
+cachetools~=5.0.0
+APScheduler~=3.9.1
+
+# pytz is required by APS and just needs the lower bound due to #2120
 pytz>=2018.6
-cachetools==4.2.2

setup.py

@@ -71,10 +71,12 @@ def get_setup_kwargs(raw=False):
         packages=packages,
         install_requires=requirements,
         extras_require={
-            'json': 'ujson',
             'socks': 'httpx[socks]',
+            # json and cryptography are very stable, so we use a reasonably new version as
+            # lower bound and have no upper bound
+            'json': 'ujson>=4.0.0',
             # 3.4-3.4.3 contained some cyclical import bugs
-            'passport': 'cryptography!=3.4,!=3.4.1,!=3.4.2,!=3.4.3',
+            'passport': 'cryptography!=3.4,!=3.4.1,!=3.4.2,!=3.4.3,>=3.0',
         },
         include_package_data=True,
         classifiers=[