tooling: Porting to poetry

.readthedocs.yaml

@@ -9,7 +9,17 @@ version: 2
 build:
   os: ubuntu-20.04
   tools:
-    python: "3.8"
+    python: "3.11"
+  jobs:
+    post_create_environment:
+      # Install poetry
+      # https://python-poetry.org/docs/#installing-manually
+      - pip install poetry
+      # Tell poetry to not use a virtual environment
+      - poetry config virtualenvs.create false
+      # Install dependencies with 'docs' dependency group
+      # https://python-poetry.org/docs/managing-dependencies/#dependency-groups
+      - poetry install --with diagrams,docs
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

CONTRIBUTING.rst

@@ -57,68 +57,72 @@ If you are proposing a feature:
 Get Started!
 ------------
 
-Ready to contribute? Here's how to set up `python-statemachine` for local development.
+Ready to contribute? Here's how to set up ``python-statemachine`` for local development.
 
-1. Fork the `python-statemachine` repo on GitHub.
-2. Clone your fork locally::
 
-    $ git clone git@github.com:your_name_here/python-statemachine.git
+1. Fork the ``python-statemachine`` repository on GitHub.
 
-3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development::
+2. Clone the forked repository to your local machine by running::
 
-    $ mkvirtualenv python-statemachine
-    $ cd python-statemachine/
-    $ python setup.py develop
+    git clone https://github.com/YOUR-USERNAME/python-statemachine.git.
 
-4. Create a branch for local development::
 
-    $ git checkout -b name-of-your-bugfix-or-feature
+3. Run ``poetry install`` to install all the dependencies and create a virtual environment::
 
-   Now you can make your changes locally.
+    poetry install
 
-5. When you're done making changes, check that your changes pass flake8 and the tests, including
-   testing other Python versions with tox::
+4. Install the pre-commit validations::
 
-    $ flake8 statemachine tests
-    $ py.test
-    $ tox
+    pre-commit install
 
-   To get flake8 and tox, just pip install them into your virtualenv.
+5. Create a branch for local development::
 
-6. To build the documentation locally, run::
+    git checkout -b name-of-your-bugfix-or-feature
 
-    $ sphinx-build docs docs/_build/html
+6. Make changes to the code.
+7. Run tests to ensure they pass by running::
 
-   Now you can serve the local documentation using a webserver, like the built-in included
-   with python::
+    poetry run pytest
 
-    $ python -m http.server --directory docs/_build/html
+8. Update the documentation as needed.
 
-   And access your browser at http://localhost:8000/
+    Build the documentation::
 
-   If you're specially writting documentation, I strongly recommend using ``sphinx-autobuild``
-   as it improves the workflow watching for file changes and with live reloading::
+        poetry run sphinx-build docs docs/_build/html
 
-    $ sphinx-autobuild docs docs/_build/html --re-ignore "auto_examples/.*"
 
-   Sometimes you need a full fresh of the files being build for docs, you can use::
+    Now you can serve the local documentation using a webserver, like the built-in included
+    with python::
 
-    $ rm -rf docs/_build/ docs/auto_examples
+        python -m http.server --directory docs/_build/html
 
-.. note::
+    And access your browser at http://localhost:8000/
+
+    If you're specially writting documentation, I strongly recommend using ``sphinx-autobuild``
+    as it improves the workflow watching for file changes and with live reloading::
+
+        poetry run sphinx-autobuild docs docs/_build/html --re-ignore "auto_examples/.*"
 
-    In order to get the tox working for all versions, I usually run pyenv enabling shell for
-    those versions::
+    Sometimes you need a full fresh of the files being build for docs, you can safelly remove
+    all automatically generated files to get a clean state by running::
 
-    $ pyenv shell 3.8.1/envs/python-statemachine 3.7.6 3.6.10 3.5.9 2.7.17
+        rm -rf docs/_build/ docs/auto_examples
 
-1. Commit your changes and push your branch to GitHub::
+9. Commit your changes and push them to your forked repository::
 
-    $ git add .
-    $ git commit -m "Your detailed description of your changes."
-    $ git push origin name-of-your-bugfix-or-feature
+    git add -A .
+    git commit -m "Your detailed description of your changes."
+    git push origin name-of-your-bugfix-or-feature
+
+10. Create a pull request on the original repository for your changes to be reviewed and potentially
+merged. Be sure to follow the project's code of conduct and contributing guidelines.
+
+
+.. note::
+
+    In order to get the tox working for all versions, I usually use pyenv enabling shell for
+    those versions.
 
-2. Submit a pull request through the GitHub website.
 
 Pull Request Guidelines
 -----------------------
@@ -128,14 +132,6 @@ Before you submit a pull request, check that it meets these guidelines:
 1. The pull request should include tests.
 2. If the pull request adds functionality, the docs should be updated. Put
    your new functionality into a function with a docstring, and add the
-   feature to the list in README.rst.
-3. The pull request should work for Python 2.7, 3.3, 3.4 and 3.5. Check
-   https://travis-ci.org/fgmacedo/python-statemachine/pull_requests
-   and make sure that the tests pass for all supported Python versions.
-
-Tips
-----
-
-To run a subset of tests::
-
-$ py.test tests.test_statemachine
+   feature to the list in the next release notes.
+3. Consider adding yourself on the contributors list.
+4. The pull request should work for all supported Python versions.

docs/_static/custom_machine.css

@@ -35,7 +35,6 @@ div.sphx-glr-download a {
     background-image: none;
     border-radius: 4px;
     border: none;
-    color: #404040 !important;
     display: inline-block;
     font-weight: bold;
     padding: 1ex;

docs/auto_examples/all_actions_machine.ipynb

@@ -26,7 +26,7 @@
       },
       "outputs": [],
       "source": [
-        "import mock\n\nfrom statemachine import State\nfrom statemachine import StateMachine\n\n\nclass AllActionsMachine(StateMachine):\n\n    initial = State(\"Initial\", initial=True)\n    final = State(\"Final\", final=True)\n\n    go = initial.to(\n        final,\n        validators=[\"validation_1\", \"validation_2\"],\n        cond=[\"condition_1\", \"condition_2\"],\n        unless=[\"unless_1\", \"unless_2\"],\n        on=[\"on_inline_1\", \"on_inline_2\"],\n        before=[\"before_go_inline_1\", \"before_go_inline_2\"],\n        after=[\"after_go_inline_1\", \"after_go_inline_2\"],\n    )\n\n    def __init__(self, *args, **kwargs):\n        self.spy = mock.Mock(side_effect=lambda x: x)\n        super(AllActionsMachine, self).__init__(*args, **kwargs)\n\n    # validators and guards\n\n    def validation_1(self):\n        # this method may raise an exception\n        return self.spy(\"validation_1\")\n\n    def validation_2(self):\n        # this method may raise an exception\n        return self.spy(\"validation_2\")\n\n    def condition_1(self):\n        self.spy(\"condition_1\")\n        return True\n\n    def condition_2(self):\n        self.spy(\"condition_2\")\n        return True\n\n    def unless_1(self):\n        self.spy(\"unless_1\")\n        return False\n\n    def unless_2(self):\n        self.spy(\"unless_2\")\n        return False\n\n    # generics state\n\n    def on_enter_state(self):\n        return self.spy(\"on_enter_state\")\n\n    def on_exit_state(self):\n        return self.spy(\"on_exit_state\")\n\n    # generics transition\n\n    def before_transition(self):\n        return self.spy(\"before_transition\")\n\n    def on_transition(self):\n        return self.spy(\"on_transition\")\n\n    def after_transition(self):\n        return self.spy(\"after_transition\")\n\n    # before / after specific\n\n    @go.before\n    def before_go_decor(self):\n        return self.spy(\"before_go_decor\")\n\n    def before_go_inline_1(self):\n        return self.spy(\"before_go_inline_1\")\n\n    def before_go_inline_2(self):\n        return self.spy(\"before_go_inline_2\")\n\n    def before_go(self):\n        return self.spy(\"before_go\")\n\n    @go.on\n    def go_on_decor(self):\n        return self.spy(\"go_on_decor\")\n\n    def on_inline_1(self):\n        return self.spy(\"on_inline_1\")\n\n    def on_inline_2(self):\n        return self.spy(\"on_inline_2\")\n\n    def on_go(self):\n        return self.spy(\"on_go\")\n\n    @go.after\n    def after_go_decor(self):\n        return self.spy(\"after_go_decor\")\n\n    def after_go_inline_1(self):\n        return self.spy(\"after_go_inline_1\")\n\n    def after_go_inline_2(self):\n        return self.spy(\"after_go_inline_2\")\n\n    def after_go(self):\n        return self.spy(\"after_go\")\n\n    # enter / exit specific\n\n    @initial.enter\n    def enter_initial_decor(self):\n        return self.spy(\"enter_initial_decor\")\n\n    def on_enter_initial(self):\n        return self.spy(\"on_enter_initial\")\n\n    @initial.exit\n    def exit_initial_decor(self):\n        return self.spy(\"exit_initial_decor\")\n\n    def on_exit_initial(self):\n        return self.spy(\"on_exit_initial\")\n\n    def on_enter_final(self):\n        return self.spy(\"on_enter_final\")\n\n    def on_exit_final(self):\n        \"hopefully this will not be called\"\n        return self.spy(\"on_exit_final\")"
+        "from unittest import mock\n\nfrom statemachine import State\nfrom statemachine import StateMachine\n\n\nclass AllActionsMachine(StateMachine):\n\n    initial = State(\"Initial\", initial=True)\n    final = State(\"Final\", final=True)\n\n    go = initial.to(\n        final,\n        validators=[\"validation_1\", \"validation_2\"],\n        cond=[\"condition_1\", \"condition_2\"],\n        unless=[\"unless_1\", \"unless_2\"],\n        on=[\"on_inline_1\", \"on_inline_2\"],\n        before=[\"before_go_inline_1\", \"before_go_inline_2\"],\n        after=[\"after_go_inline_1\", \"after_go_inline_2\"],\n    )\n\n    def __init__(self, *args, **kwargs):\n        self.spy = mock.Mock(side_effect=lambda x: x)\n        super(AllActionsMachine, self).__init__(*args, **kwargs)\n\n    # validators and guards\n\n    def validation_1(self):\n        # this method may raise an exception\n        return self.spy(\"validation_1\")\n\n    def validation_2(self):\n        # this method may raise an exception\n        return self.spy(\"validation_2\")\n\n    def condition_1(self):\n        self.spy(\"condition_1\")\n        return True\n\n    def condition_2(self):\n        self.spy(\"condition_2\")\n        return True\n\n    def unless_1(self):\n        self.spy(\"unless_1\")\n        return False\n\n    def unless_2(self):\n        self.spy(\"unless_2\")\n        return False\n\n    # generics state\n\n    def on_enter_state(self):\n        return self.spy(\"on_enter_state\")\n\n    def on_exit_state(self):\n        return self.spy(\"on_exit_state\")\n\n    # generics transition\n\n    def before_transition(self):\n        return self.spy(\"before_transition\")\n\n    def on_transition(self):\n        return self.spy(\"on_transition\")\n\n    def after_transition(self):\n        return self.spy(\"after_transition\")\n\n    # before / after specific\n\n    @go.before\n    def before_go_decor(self):\n        return self.spy(\"before_go_decor\")\n\n    def before_go_inline_1(self):\n        return self.spy(\"before_go_inline_1\")\n\n    def before_go_inline_2(self):\n        return self.spy(\"before_go_inline_2\")\n\n    def before_go(self):\n        return self.spy(\"before_go\")\n\n    @go.on\n    def go_on_decor(self):\n        return self.spy(\"go_on_decor\")\n\n    def on_inline_1(self):\n        return self.spy(\"on_inline_1\")\n\n    def on_inline_2(self):\n        return self.spy(\"on_inline_2\")\n\n    def on_go(self):\n        return self.spy(\"on_go\")\n\n    @go.after\n    def after_go_decor(self):\n        return self.spy(\"after_go_decor\")\n\n    def after_go_inline_1(self):\n        return self.spy(\"after_go_inline_1\")\n\n    def after_go_inline_2(self):\n        return self.spy(\"after_go_inline_2\")\n\n    def after_go(self):\n        return self.spy(\"after_go\")\n\n    # enter / exit specific\n\n    @initial.enter\n    def enter_initial_decor(self):\n        return self.spy(\"enter_initial_decor\")\n\n    def on_enter_initial(self):\n        return self.spy(\"on_enter_initial\")\n\n    @initial.exit\n    def exit_initial_decor(self):\n        return self.spy(\"exit_initial_decor\")\n\n    def on_exit_initial(self):\n        return self.spy(\"on_exit_initial\")\n\n    def on_enter_final(self):\n        return self.spy(\"on_enter_final\")\n\n    def on_exit_final(self):\n        \"hopefully this will not be called\"\n        return self.spy(\"on_exit_final\")"
       ]
     },
     {

docs/auto_examples/all_actions_machine.py

@@ -5,7 +5,7 @@
 A StateMachine that exercices all possible :ref:`Actions` and :ref:`Guards`.
 
 """
-import mock
+from unittest import mock
 
 from statemachine import State
 from statemachine import StateMachine

docs/auto_examples/all_actions_machine.py.md5

@@ -1 +1 @@
-ac78776e5717c75cacc8861a2f267168
+bc9e763d829c16d3337524a4db82811a

docs/auto_examples/all_actions_machine.rst

@@ -27,7 +27,7 @@ A StateMachine that exercices all possible :ref:`Actions` and :ref:`Guards`.
 
 .. code-block:: default
 
-    import mock
+    from unittest import mock
 
     from statemachine import State
     from statemachine import StateMachine

docs/examples/patch_repr_svg.py

@@ -1,7 +1,7 @@
 import sys
 
 
-def patch__repr_html_():  # pragma: no cover
+def patch__repr_html():  # pragma: no cover
     """
     You're running this example directly from your browser! By using the amazing
     https://pyodide.org/.
@@ -27,10 +27,11 @@ def show_sm(sm):
         return '<svg width="auto" height="auto"><image xlink:href="{}"/>'.format(url)
 
     StateMachine._repr_html_ = show_sm
+    StateMachine._repr_svg_ = show_sm
 
 
 if sys.platform == "emscripten":  # pragma: no cover
     # https://pyodide.org/ is the runtime!
-    patch__repr_html_()
-    print(patch__repr_html_.__doc__)
+    patch__repr_html()
+    print(patch__repr_html.__doc__)
     print("'StateMachine._repr_html_' patched!")

docs/requirements.txt

@@ -1,10 +1,4 @@
-# docs
-Sphinx<5.0.0
-sphinx_rtd_theme==1.1.1
-sphinx-markdown-builder==0.5.5
-myst-parser==0.18.1
-jupyterlite-sphinx==0.7.2
-sphinx-gallery==0.11.1
-matplotlib==3.6.2
-
-pydot
+# Temp file while readthedocs dont enable USE_SPHINX_LATEST on this project
+# https://github.com/readthedocs/readthedocs.org/issues/7858#issuecomment-764886373
+Sphinx==4.5.0
+sphinx-rtd-theme==1.1.1