python-telegram-bot · pavel-ignatovich · Jul 14, 2021 · Aug 11, 2021 · Aug 11, 2021 · Aug 12, 2021
diff --git a/.github/CONTRIBUTING.rst b/.github/CONTRIBUTING.rst
@@ -71,29 +71,9 @@ Here's how to make a one-off code change.
 
    - Your code should adhere to the `PEP 8 Style Guide`_, with the exception that we have a maximum line length of 99.
 
-   - Provide static typing with signature annotations. The documentation of `MyPy`_ will be a good start, the cheat sheet is `here`_. We also have some custom type aliases in ``telegram.utils.helpers.typing``.
+   - Provide static typing with signature annotations. The documentation of `MyPy`_ will be a good start, the cheat sheet is `here`_. We also have some custom type aliases in ``telegram._utils.types``.
 
-   - Document your code. This project uses `sphinx`_ to generate static HTML docs. To build them, first make sure you have the required dependencies:
-
-     .. code-block:: bash
-
-        $ pip install -r docs/requirements-docs.txt
-
-     then run the following from the PTB root directory:
-
-     .. code-block:: bash
-
-        $ make -C docs html
-
-     or, if you don't have ``make`` available (e.g. on Windows):
-
-     .. code-block:: bash
-
-        $ sphinx-build docs/source docs/build/html
-
-     Once the process terminates, you can view the built documentation by opening ``docs/build/html/index.html`` with a browser.
-
-   - Add ``.. versionadded:: version``, ``.. versionchanged:: version`` or ``.. deprecated:: version`` to the associated documentation of your changes, depending on what kind of change you made. This only applies if the change you made is visible to an end user. The directives should be added to class/method descriptions if their general behaviour changed and to the description of all arguments & attributes that changed.
+   - Document your code. This step is pretty important to us, so it has its own `section`_.
 
    - For consistency, please conform to `Google Python Style Guide`_ and `Google Python Style Docstrings`_.
 
@@ -105,6 +85,8 @@ Here's how to make a one-off code change.
 
    - Please ensure that the code you write is well-tested.
 
+        - In addition to that, we provide the `dev` marker for pytest. If you write one or multiple tests and want to run only those, you can decorate them via `@pytest.mark.dev` and then run it with minimal overhead with `pytest ./path/to/test_file.py -m dev`.
+
    - Don’t break backward compatibility.
 
    - Add yourself to the AUTHORS.rst_ file in an alphabetical fashion.
@@ -151,10 +133,12 @@ Here's how to make a one-off code change.
 
 5. **Address review comments until all reviewers give LGTM ('looks good to me').**
 
-   - When your reviewer has reviewed the code, you'll get an email. You'll need to respond in two ways:
+   - When your reviewer has reviewed the code, you'll get a notification. You'll need to respond in two ways:
 
        - Make a new commit addressing the comments you agree with, and push it to the same branch. Ideally, the commit message would explain what the commit does (e.g. "Fix lint error"), but if there are lots of disparate review comments, it's fine to refer to the original commit message and add something like "(address review comments)".
 
+       - In order to keep the commit history intact, please avoid squashing or amending history and then force-pushing to the PR. Reviewers often want to look at individual commits.
+
        - In addition, please reply to each comment. Each reply should be either "Done" or a response explaining why the corresponding suggestion wasn't implemented. All comments must be resolved before LGTM can be given.
 
    - Resolve any merge conflicts that arise. To resolve conflicts between 'your-branch-name' (in your fork) and 'master' (in the ``python-telegram-bot`` repository), run:
@@ -186,6 +170,49 @@ Here's how to make a one-off code change.
 
 7. **Celebrate.** Congratulations, you have contributed to ``python-telegram-bot``!
 
+Documenting
+===========
+
+The documentation of this project is separated in two sections: User facing and dev facing.
+
+User facing docs are hosted at `RTD`_. They are the main way the users of our library are supposed to get information about the objects. They don't care about the internals, they just want to know
+what they have to pass to make it work, what it actually does. You can/should provide examples for non obvious cases (like the Filter module), and notes/warnings.
+
+Dev facing, on the other side, is for the devs/maintainers of this project. These
+doc strings don't have a separate documentation site they generate, instead, they document the actual code.
+
+User facing documentation
+-------------------------
+We use `sphinx`_ to generate static HTML docs. To build them, first make sure you have the required dependencies:
+
+.. code-block:: bash
+
+   $ pip install -r docs/requirements-docs.txt
+
+then run the following from the PTB root directory:
+
+.. code-block:: bash
+
+   $ make -C docs html
+
+or, if you don't have ``make`` available (e.g. on Windows):
+
+.. code-block:: bash
+
+   $ sphinx-build docs/source docs/build/html
+
+Once the process terminates, you can view the built documentation by opening ``docs/build/html/index.html`` with a browser.
+
+- Add ``.. versionadded:: version``, ``.. versionchanged:: version`` or ``.. deprecated:: version`` to the associated documentation of your changes, depending on what kind of change you made. This only applies if the change you made is visible to an end user. The directives should be added to class/method descriptions if their general behaviour changed and to the description of all arguments & attributes that changed.
+
+Dev facing documentation
+------------------------
+We adhere to the `CSI`_ standard. This documentation is not fully implemented in the project, yet, but new code changes should comply with the `CSI` standard.
+The idea behind this is to make it very easy for you/a random maintainer or even a totally foreign person to drop anywhere into the code and more or less immediately understand what a particular line does. This will make it easier
+for new to make relevant changes if said lines don't do what they are supposed to.
+
+
+
 Style commandments
 ------------------
 
@@ -252,4 +279,7 @@ break the API classes. For example:
 .. _`here`: https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html
 .. _`Black`: https://black.readthedocs.io/en/stable/index.html
 .. _`popular editors`: https://black.readthedocs.io/en/stable/editor_integration.html
+.. _`RTD`: https://python-telegram-bot.readthedocs.io/
 .. _`RTD build`: https://python-telegram-bot.readthedocs.io/en/doc-fixes
+.. _`CSI`: https://standards.mousepawmedia.com/en/stable/csi.html
+.. _`section`: #documenting
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -6,6 +6,7 @@ Hey! You're PRing? Cool! Please have a look at the below checklist. It's here to
 
 - [ ] Added `.. versionadded:: version`, `.. versionchanged:: version` or `.. deprecated:: version` to the docstrings for user facing changes (for methods/class descriptions, arguments and attributes)
 - [ ] Created new or adapted existing unit tests
+- [ ] Documented code changes according to the [CSI standard](https://standards.mousepawmedia.com/en/stable/csi.html)
 - [ ] Added myself alphabetically to `AUTHORS.rst` (optional)
 - [ ] Added new classes & modules to the docs
 
@@ -25,8 +26,12 @@ Hey! You're PRing? Cool! Please have a look at the below checklist. It's here to
 * If relevant:
 
     - [ ] Added new constants at `telegram.constants` and shortcuts to them as class variables
+    - [ ] Link new and existing constants in docstrings instead of hard coded number and strings
+    - [ ] Add new message types to `Message.effective_attachment`
     - [ ] Added new handlers for new update types
+      - [ ] Add the handlers to the warning loop in the `ConversationHandler`
     - [ ] Added new filters for new message (sub)types
     - [ ] Added or updated documentation for the changed class(es) and/or method(s)
+    - [ ] Added or updated `bot_methods.rst`
     - [ ] Updated the Bot API version number in all places: `README.rst` and `README_RAW.rst` (including the badge), as well as `telegram.constants.BOT_API_VERSION`
     - [ ] Added logic for arbitrary callback data in `tg.ext.Bot` for new methods that either accept a `reply_markup` in some form or have a return type that is/contains `telegram.Message`
diff --git a/.github/workflows/example_notifier.yml b/.github/workflows/example_notifier.yml
@@ -1,6 +1,6 @@
 name: Warning maintainers
 on:
-  pull_request:
+  pull_request_target:
     paths: examples/**
 jobs:
   job:

diff --git a/.github/workflows/pre-commit_dependencies_notifier.yml b/.github/workflows/pre-commit_dependencies_notifier.yml
@@ -1,6 +1,6 @@
 name: Warning maintainers
 on:
-  pull_request:
+  pull_request_target:
     paths:
       - requirements.txt
       - requirements-dev.txt

diff --git a/.github/workflows/readme_notifier.yml b/.github/workflows/readme_notifier.yml
@@ -1,6 +1,6 @@
 name: Warning maintainers
 on:
-  pull_request:
+  pull_request_target:
     paths:
       - README.rst
       - README_RAW.rst

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -3,17 +3,19 @@ on:
   pull_request:
     branches:
       - master
+      - v14
   push:
     branches: 
       - master
+      - v14
 
 jobs:
   pytest:
     name: pytest
     runs-on: ${{matrix.os}}
     strategy:
       matrix:
-        python-version: [3.6, 3.7, 3.8, 3.9]
+        python-version: [3.7, 3.8, 3.9]
         os: [ubuntu-latest, windows-latest, macos-latest]
       fail-fast: False
     steps:
@@ -34,7 +36,7 @@ jobs:
 
       - name: Test with pytest
         # We run 3 different suites here
-        # 1. Test just utils.helpers.py without pytz being installed
+        # 1. Test just utils.datetime.py without pytz being installed
         # 2. Test just test_no_passport.py without passport dependencies being installed
         # 3. Test everything else
         # The first & second one are achieved by mocking the corresponding import

diff --git a/.gitignore b/.gitignore
@@ -69,6 +69,9 @@ target/
 # Sublime Text 2
 *.sublime*
 
+# VS Code
+.vscode
+
 # unitests files
 game.gif
 telegram.mp3

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -3,36 +3,43 @@
 #   * the additional_dependencies here match requirements.txt
 repos:
 -   repo: https://github.com/psf/black
-    rev: 20.8b1
+    rev: 21.9b0
     hooks:
     -   id: black
         args:
         - --diff
         - --check
 -   repo: https://gitlab.com/pycqa/flake8
-    rev: 3.9.2
+    rev: 4.0.1
     hooks:
     -   id: flake8
 -   repo: https://github.com/PyCQA/pylint
-    rev: v2.8.3
+    rev: v2.12.1
     hooks:
     -   id: pylint
         files: ^(telegram|examples)/.*\.py$
         args:
           - --rcfile=setup.cfg
+          #  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:
           - certifi
           - tornado>=6.1
           - APScheduler==3.6.3
           - cachetools==4.2.2
           - . # this basically does `pip install -e .`
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.812
+    rev: v0.910
     hooks:
     -   id: mypy
         name: mypy-ptb
         files: ^telegram/.*\.py$
         additional_dependencies:
+          - types-ujson
+          - types-pytz
+          - types-cryptography
+          - types-certifi
+          - types-cachetools
           - certifi
           - tornado>=6.1
           - APScheduler==3.6.3
@@ -51,9 +58,9 @@ repos:
           - cachetools==4.2.2
           - . # this basically does `pip install -e .`
 -   repo: https://github.com/asottile/pyupgrade
-    rev: v2.19.1
+    rev: v2.29.0
     hooks:
     -   id: pyupgrade
         files: ^(telegram|examples|tests)/.*\.py$
         args:
-          - --py36-plus
+          - --py37-plus
diff --git a/AUTHORS.rst b/AUTHORS.rst
@@ -43,6 +43,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `DonalDuck004 <https://github.com/DonalDuck004>`_
 - `Eana Hufwe <https://github.com/blueset>`_
 - `Ehsan Online <https://github.com/ehsanonline>`_
+- `Eldad Carin <https://github.com/eldbud>`_
 - `Eli Gao <https://github.com/eligao>`_
 - `Emilio Molinari <https://github.com/xates>`_
 - `ErgoZ Riftbit Vaper <https://github.com/ergoz>`_
@@ -67,6 +68,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Joscha Götzer <https://github.com/Rostgnom>`_
 - `jossalgon <https://github.com/jossalgon>`_
 - `JRoot3D <https://github.com/JRoot3D>`_
+- `kennethcheo <https://github.com/kennethcheo>`_
 - `Kirill Vasin <https://github.com/vasinkd>`_
 - `Kjwon15 <https://github.com/kjwon15>`_
 - `Li-aung Yip <https://github.com/LiaungYip>`_
@@ -90,6 +92,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Patrick Hofmann <https://github.com/PH89>`_
 - `Paul Larsen <https://github.com/PaulSonOfLars>`_
 - `Pieter Schutz <https://github.com/eldinnie>`_
+- `Piraty <https://github.com/piraty>`_
 - `Poolitzer <https://github.com/Poolitzer>`_
 - `Pranjalya Tiwari <https://github.com/Pranjalya>`_
 - `Rahiel Kasim <https://github.com/rahiel>`_
@@ -111,5 +114,6 @@ The following wonderful people contributed directly or indirectly to this projec
 - `wjt <https://github.com/wjt>`_
 - `zeroone2numeral2 <https://github.com/zeroone2numeral2>`_
 - `zeshuaro <https://github.com/zeshuaro>`_
+- `zpavloudis <https://github.com/zpavloudis>`_
 
 Please add yourself here alphabetically when you submit your first pull request.
diff --git a/README.rst b/README.rst
@@ -93,7 +93,7 @@ Introduction
 
 This library provides a pure Python interface for the
 `Telegram Bot API <https://core.telegram.org/bots/api>`_.
-It's compatible with Python versions 3.6.8+. PTB might also work on `PyPy <http://pypy.org/>`_, though there have been a lot of issues before. Hence, PyPy is not officially supported.
+It's compatible with Python versions **3.7+**. PTB might also work on `PyPy <http://pypy.org/>`_, though there have been a lot of issues before. Hence, PyPy is not officially supported.
 
 In addition to the pure API implementation, this library features a number of high-level classes to
 make the development of bots easy and straightforward. These classes are contained in the
@@ -144,7 +144,7 @@ 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[ujson]`` 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[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.
 
 ===============
@@ -167,8 +167,8 @@ Learning by example
 
 We believe that the best way to learn this package is by example. Here
 are some examples for you to review. Even if it is not your approach for learning, please take a
-look at ``echobot.py``, it is the de facto base for most of the bots out there. Best of all,
-the code for these examples are released to the public domain, so you can start by grabbing the
+look at ``echobot.py``. It is the de facto base for most of the bots out there. Best of all,
+the code for these examples is released to the public domain, so you can start by grabbing the
 code and building on top of it.
 
 Visit `this page <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/README.md>`_ to discover the official examples or look at the examples on the `wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Examples>`_ to see other bots the community has built.
@@ -231,7 +231,7 @@ Contributions of all sizes are welcome. Please review our `contribution guidelin
 ========
 Donating
 ========
-Occasionally we are asked if we accept donations to support the development. While we appreciate the thought, maintaining PTB is our hobby and we have almost no running costs for it. We therefore have nothing set up to accept donations. If you still want to donate, we kindly ask you to donate to another open source project/initiative of your choice instead.
+Occasionally we are asked if we accept donations to support the development. While we appreciate the thought, maintaining PTB is our hobby, and we have almost no running costs for it. We therefore have nothing set up to accept donations. If you still want to donate, we kindly ask you to donate to another open source project/initiative of your choice instead.
 
 =======
 License

diff --git a/README_RAW.rst b/README_RAW.rst
@@ -91,7 +91,7 @@ Introduction
 
 This library provides a pure Python, lightweight interface for the
 `Telegram Bot API <https://core.telegram.org/bots/api>`_.
-It's compatible with Python versions 3.6.8+. PTB-Raw might also work on `PyPy <http://pypy.org/>`_, though there have been a lot of issues before. Hence, PyPy is not officially supported.
+It's compatible with Python versions **3.7+**. PTB-Raw might also work on `PyPy <http://pypy.org/>`_, though there have been a lot of issues before. Hence, PyPy is not officially supported.
 
 ``python-telegram-bot-raw`` is part of the `python-telegram-bot <https://python-telegram-bot.org>`_ ecosystem and provides the pure API functionality extracted from PTB. It therefore does *not* have independent release schedules, changelogs or documentation. Please consult the PTB resources.
 
@@ -144,7 +144,7 @@ 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[ujson]`` 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[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.
 
 ===============
 Getting started
@@ -213,7 +213,7 @@ Contributions of all sizes are welcome. Please review our `contribution guidelin
 ========
 Donating
 ========
-Occasionally we are asked if we accept donations to support the development. While we appreciate the thought, maintaining PTB is our hobby and we have almost no running costs for it. We therefore have nothing set up to accept donations. If you still want to donate, we kindly ask you to donate to another open source project/initiative of your choice instead.
+Occasionally we are asked if we accept donations to support the development. While we appreciate the thought, maintaining PTB is our hobby, and we have almost no running costs for it. We therefore have nothing set up to accept donations. If you still want to donate, we kindly ask you to donate to another open source project/initiative of your choice instead.
 
 =======
 License

diff --git a/docs/Makefile b/docs/Makefile
@@ -15,7 +15,7 @@ endif
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -j auto
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 

diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt
@@ -1,6 +1,3 @@
-sphinx==3.5.4
+sphinx==4.3.2
 sphinx-pypi-upload
-# When bumping this, make sure to rebuild the dark-mode CSS
-# More instructions at source/_static/dark.css
-# Ofc once https://github.com/readthedocs/sphinx_rtd_theme/issues/224 is closed, we should use that
-sphinx_rtd_theme==0.5.2
+furo