python-telegram-bot · starry-shivam · Jul 14, 2021 · Aug 11, 2021 · Aug 11, 2021 · Aug 12, 2021
diff --git a/.github/CONTRIBUTING.rst b/.github/CONTRIBUTING.rst
@@ -73,27 +73,7 @@ Here's how to make a one-off code change.
 
    - 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``.
 
-   - 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,7 +133,7 @@ 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)".
 
@@ -186,6 +168,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 +277,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)
 
 

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:

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -20,6 +20,8 @@ repos:
         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
@@ -56,4 +58,4 @@ repos:
     -   id: pyupgrade
         files: ^(telegram|examples|tests)/.*\.py$
         args:
-          - --py36-plus
+          - --py37-plus
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

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.
 

diff --git a/docs/source/telegram.ext.delayqueue.rst b/docs/source/telegram.ext.delayqueue.rst
diff --git a/docs/source/telegram.ext.messagequeue.rst b/docs/source/telegram.ext.messagequeue.rst
diff --git a/docs/source/telegram.ext.persistenceinput.rst b/docs/source/telegram.ext.persistenceinput.rst
@@ -0,0 +1,7 @@
+:github_url: https://github.com/python-telegram-bot/python-telegram-bot/blob/master/telegram/ext/basepersistence.py
+
+telegram.ext.PersistenceInput
+=============================
+
+.. autoclass:: telegram.ext.PersistenceInput
+    :show-inheritance:
diff --git a/docs/source/telegram.ext.regexhandler.rst b/docs/source/telegram.ext.regexhandler.rst
diff --git a/docs/source/telegram.ext.rst b/docs/source/telegram.ext.rst
@@ -10,8 +10,6 @@ telegram.ext package
     telegram.ext.callbackcontext
     telegram.ext.job
     telegram.ext.jobqueue
-    telegram.ext.messagequeue
-    telegram.ext.delayqueue
     telegram.ext.contexttypes
     telegram.ext.defaults
 
@@ -33,7 +31,6 @@ Handlers
     telegram.ext.pollhandler
     telegram.ext.precheckoutqueryhandler
     telegram.ext.prefixhandler
-    telegram.ext.regexhandler
     telegram.ext.shippingqueryhandler
     telegram.ext.stringcommandhandler
     telegram.ext.stringregexhandler
@@ -45,6 +42,7 @@ Persistence
 .. toctree::
 
     telegram.ext.basepersistence
+    telegram.ext.persistenceinput
     telegram.ext.picklepersistence
     telegram.ext.dictpersistence
 

diff --git a/examples/arbitrarycallbackdatabot.py b/examples/arbitrarycallbackdatabot.py
@@ -20,15 +20,15 @@
 )
 
 logging.basicConfig(
-    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', level=logging.INFO
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s", level=logging.INFO
 )
 logger = logging.getLogger(__name__)
 
 
 def start(update: Update, context: CallbackContext) -> None:
     """Sends a message with 5 inline buttons attached."""
     number_list: List[int] = []
-    update.message.reply_text('Please choose:', reply_markup=build_keyboard(number_list))
+    update.message.reply_text("Please choose:", reply_markup=build_keyboard(number_list))
 
 
 def help_command(update: Update, context: CallbackContext) -> None:
@@ -43,7 +43,7 @@ def clear(update: Update, context: CallbackContext) -> None:
     """Clears the callback data cache"""
     context.bot.callback_data_cache.clear_callback_data()  # type: ignore[attr-defined]
     context.bot.callback_data_cache.clear_callback_queries()  # type: ignore[attr-defined]
-    update.effective_message.reply_text('All clear!')
+    update.effective_message.reply_text("All clear!")
 
 
 def build_keyboard(current_list: List[int]) -> InlineKeyboardMarkup:
@@ -77,22 +77,20 @@ def handle_invalid_button(update: Update, context: CallbackContext) -> None:
     """Informs the user that the button is no longer available."""
     update.callback_query.answer()
     update.effective_message.edit_text(
-        'Sorry, I could not process this button click 😕 Please send /start to get a new keyboard.'
+        "Sorry, I could not process this button click 😕 Please send /start to get a new keyboard."
     )
 
 
 def main() -> None:
     """Run the bot."""
     # We use persistence to demonstrate how buttons can still work after the bot was restarted
-    persistence = PicklePersistence(
-        filename='arbitrarycallbackdatabot.pickle', store_callback_data=True
-    )
+    persistence = PicklePersistence(filename="arbitrarycallbackdatabot.pickle")
     # Create the Updater and pass it your bot's token.
     updater = Updater("TOKEN", persistence=persistence, arbitrary_callback_data=True)
 
-    updater.dispatcher.add_handler(CommandHandler('start', start))
-    updater.dispatcher.add_handler(CommandHandler('help', help_command))
-    updater.dispatcher.add_handler(CommandHandler('clear', clear))
+    updater.dispatcher.add_handler(CommandHandler("start", start))
+    updater.dispatcher.add_handler(CommandHandler("help", help_command))
+    updater.dispatcher.add_handler(CommandHandler("clear", clear))
     updater.dispatcher.add_handler(
         CallbackQueryHandler(handle_invalid_button, pattern=InvalidCallbackData)
     )
@@ -106,5 +104,5 @@ def main() -> None:
     updater.idle()
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     main()
diff --git a/examples/contexttypesbot.py b/examples/contexttypesbot.py
@@ -43,7 +43,7 @@ def __init__(self, dispatcher: Dispatcher):
     @property
     def bot_user_ids(self) -> Set[int]:
         """Custom shortcut to access a value stored in the bot_data dict"""
-        return self.bot_data.setdefault('user_ids', set())
+        return self.bot_data.setdefault("user_ids", set())
 
     @property
     def message_clicks(self) -> Optional[int]:
@@ -56,11 +56,11 @@ def message_clicks(self) -> Optional[int]:
     def message_clicks(self, value: int) -> None:
         """Allow to change the count"""
         if not self._message_id:
-            raise RuntimeError('There is no message associated with this context obejct.')
+            raise RuntimeError("There is no message associated with this context obejct.")
         self.chat_data.clicks_per_message[self._message_id] = value
 
     @classmethod
-    def from_update(cls, update: object, dispatcher: 'Dispatcher') -> 'CustomContext':
+    def from_update(cls, update: object, dispatcher: "Dispatcher") -> "CustomContext":
         """Override from_update to set _message_id."""
         # Make sure to call super()
         context = super().from_update(update, dispatcher)
@@ -75,9 +75,9 @@ def from_update(cls, update: object, dispatcher: 'Dispatcher') -> 'CustomContext
 def start(update: Update, context: CustomContext) -> None:
     """Display a message with a button."""
     update.message.reply_html(
-        'This button was clicked <i>0</i> times.',
+        "This button was clicked <i>0</i> times.",
         reply_markup=InlineKeyboardMarkup.from_button(
-            InlineKeyboardButton(text='Click me!', callback_data='button')
+            InlineKeyboardButton(text="Click me!", callback_data="button")
         ),
     )
 
@@ -87,9 +87,9 @@ def count_click(update: Update, context: CustomContext) -> None:
     context.message_clicks += 1
     update.callback_query.answer()
     update.effective_message.edit_text(
-        f'This button was clicked <i>{context.message_clicks}</i> times.',
+        f"This button was clicked <i>{context.message_clicks}</i> times.",
         reply_markup=InlineKeyboardMarkup.from_button(
-            InlineKeyboardButton(text='Click me!', callback_data='button')
+            InlineKeyboardButton(text="Click me!", callback_data="button")
         ),
         parse_mode=ParseMode.HTML,
     )
@@ -98,7 +98,7 @@ def count_click(update: Update, context: CustomContext) -> None:
 def print_users(update: Update, context: CustomContext) -> None:
     """Show which users have been using this bot."""
     update.message.reply_text(
-        'The following user IDs have used this bot: '
+        "The following user IDs have used this bot: "
         f'{", ".join(map(str, context.bot_user_ids))}'
     )
 
@@ -125,5 +125,5 @@ def main() -> None:
     updater.idle()
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     main()