diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 1e8de91c7..25f102154 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -20,7 +20,7 @@ repos: - id: check-yaml files: .*\.(yaml|yml)$ - repo: https://github.com/codespell-project/codespell.git - rev: v2.1.0 + rev: v2.2.1 hooks: - id: codespell name: codespell diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 000000000..9466a596b --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,7 @@ +{ + "recommendations": [ + "ms-azuretools.vscode-docker", + "ms-vscode-remote.remote-containers", + "njpwerner.autodocstring" + ] +} diff --git a/README.rst b/README.rst index b3ea8671b..0aa704854 100644 --- a/README.rst +++ b/README.rst @@ -88,53 +88,36 @@ Setup ===== * Fork_ repo * Keep it sync_'ed while you are developing -* Install pyenv_ -* develop and test - * Launch docker jira server - - ``docker run -dit -p 2990:2990 --name jira addono/jira-software-standalone`` - * Lint - - ``tox -e lint`` - * Run tests - - ``tox`` - * Run tests for one env only - - ``tox -e py38`` - * Specify what tests to run with pytest_ - - ``tox -e py39 -- tests/resources/test_attachment.py`` - * Debug tests with breakpoints by disabling the coverage plugin, with the ``--no-cov`` argument. - - Example for VSCode on Windows : - - .. code-block:: java - - { - "name": "Pytest", - "type": "python", - "request": "launch", - "python": ".tox\\py39\\Scripts\\python.exe", - "module": "pytest", - "env": { - "CI_JIRA_URL": "http://localhost:2990/jira", - "CI_JIRA_ADMIN": "admin", - "CI_JIRA_ADMIN_PASSWORD": "admin", - "CI_JIRA_USER": "jira_user", - "CI_JIRA_USER_FULL_NAME": "Newly Created CI User", - "CI_JIRA_USER_PASSWORD": "jira", - "CI_JIRA_ISSUE": "Task", - "PYTEST_TIMEOUT": "0", // Don't timeout - }, - "args": [ - // "-v", - "--no-cov", // running coverage affects breakpoints - "tests/resources/test_attachment.py" - ] - } - - * Build and publish with TWINE - - ``tox -e publish`` + +Automatic (VS Code) +``````````````````` +.. image:: https://img.shields.io/static/v1?label=Remote%20-%20Containers&message=Open&color=blue&logo=visualstudiocode + :target: https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/pycontribs/jira + :alt: Open in Remote - Containers + +Follow the instructions in the `contributing guide`_, which will describe how to use the dev container +that will automatically setup a suitable environment. + +Manual +`````` +* Install pyenv_ to install a suitable python version. +* Launch docker jira server + - ``docker run -dit -p 2990:2990 --name jira addono/jira-software-standalone`` + +tox envs +```````` +* Lint + - ``tox -e lint`` +* Run tests + - ``tox`` +* Build and publish with TWINE + - ``tox -e publish`` .. _Fork: https://help.github.com/articles/fork-a-repo/ .. _sync: https://help.github.com/articles/syncing-a-fork/ .. _pyenv: https://amaral.northwestern.edu/resources/guides/pyenv-tutorial .. _pytest: https://docs.pytest.org/en/stable/usage.html#specifying-tests-selecting-tests +.. _contributing guide: https://jira.readthedocs.io/contributing.html Jira REST API Reference Links diff --git a/constraints.txt b/constraints.txt index 3201ff956..63a83657a 100644 --- a/constraints.txt +++ b/constraints.txt @@ -16,20 +16,22 @@ babel==2.10.3 # via sphinx backcall==0.2.0 # via ipython +beautifulsoup4==4.11.1 + # via furo certifi==2022.6.15 # via requests -cffi==1.15.0 +cffi==1.15.1 # via cryptography -charset-normalizer==2.1.0 +charset-normalizer==2.1.1 # via requests colorama==0.4.5 # via # ipython # pytest # sphinx -coverage==6.4.1 +coverage==6.4.4 # via pytest-cov -cryptography==37.0.2 +cryptography==37.0.4 # via # pyspnego # requests-kerberos @@ -37,42 +39,45 @@ decorator==5.1.1 # via ipython defusedxml==0.7.1 # via jira (setup.cfg) -docutils==0.17.1 +docutils==0.19 # via # jira (setup.cfg) # sphinx - # sphinx-rtd-theme execnet==1.9.0 # via # pytest-cache # pytest-xdist -executing==0.8.3 +executing==0.10.0 # via stack-data filemagic==1.6 # via jira (setup.cfg) flaky==3.7.0 # via jira (setup.cfg) +furo==2022.6.21 + # via jira (setup.cfg) idna==3.3 # via requests imagesize==1.4.1 # via sphinx importlib-metadata==4.12.0 - # via keyring + # via + # keyring + # sphinx iniconfig==1.1.1 # via pytest -ipython==8.2.0 +ipython==8.4.0 # via jira (setup.cfg) jedi==0.18.1 # via ipython jinja2==3.1.2 # via sphinx -keyring==23.5.0 +keyring==23.8.2 # via jira (setup.cfg) markupsafe==2.1.1 # via # jinja2 # jira (setup.cfg) -matplotlib-inline==0.1.3 +matplotlib-inline==0.1.6 # via ipython oauthlib==3.2.0 # via @@ -80,6 +85,7 @@ oauthlib==3.2.0 # requests-oauthlib packaging==21.3 # via + # jira (setup.cfg) # pytest # pytest-sugar # sphinx @@ -104,17 +110,18 @@ pycparser==2.21 # via cffi pygments==2.13.0 # via + # furo # ipython # sphinx pyjwt==2.4.0 # via # jira (setup.cfg) # requests-jwt -pyparsing==3.0.7 +pyparsing==3.0.9 # via packaging -pyspnego==0.5.4 +pyspnego==0.6.0 # via requests-kerberos -pytest==7.1.1 +pytest==7.1.2 # via # jira (setup.cfg) # pytest-cache @@ -138,7 +145,7 @@ pytest-timeout==2.1.0 # via jira (setup.cfg) pytest-xdist==2.5.0 # via jira (setup.cfg) -pytz==2022.1 +pytz==2022.2.1 # via babel pywin32-ctypes==0.2.0 # via keyring @@ -175,11 +182,17 @@ six==1.16.0 # requests-mock snowballstemmer==2.2.0 # via sphinx +soupsieve==2.3.2.post1 + # via beautifulsoup4 sphinx==5.1.1 # via + # furo # jira (setup.cfg) - # sphinx-rtd-theme -sphinx-rtd-theme==1.0.0 + # sphinx-basic-ng + # sphinx-copybutton +sphinx-basic-ng==0.0.1a12 + # via furo +sphinx-copybutton==0.5.0 # via jira (setup.cfg) sphinxcontrib-applehelp==1.0.2 # via sphinx @@ -203,13 +216,13 @@ tomli==2.0.1 # via # coverage # pytest -traitlets==5.1.1 +traitlets==5.3.0 # via # ipython # matplotlib-inline typing-extensions==4.3.0 # via jira (setup.cfg) -urllib3==1.26.11 +urllib3==1.26.12 # via requests wcwidth==0.2.5 # via prompt-toolkit @@ -219,8 +232,5 @@ xmlrunner==1.7.7 # via jira (setup.cfg) yanc==0.3.3 # via jira (setup.cfg) -zipp==3.8.0 +zipp==3.8.1 # via importlib-metadata - -# The following packages are considered to be unsafe in a requirements file: -# setuptools diff --git a/docs/_static/.placeholder b/docs/_static/.placeholder deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/_static/css/custom_width.css b/docs/_static/css/custom_width.css deleted file mode 100644 index f9c89c8d2..000000000 --- a/docs/_static/css/custom_width.css +++ /dev/null @@ -1,5 +0,0 @@ -@import url("theme.css"); -/* as found in https://stackoverflow.com/a/62338678/2559785 */ -.wy-nav-content { - max-width: 90%; !important -} diff --git a/docs/_static/python-16.png b/docs/_static/python-16.png deleted file mode 100644 index d1c07f0a8..000000000 Binary files a/docs/_static/python-16.png and /dev/null differ diff --git a/docs/_static/python-256.png b/docs/_static/python-256.png deleted file mode 100644 index e0d06ffc9..000000000 Binary files a/docs/_static/python-256.png and /dev/null differ diff --git a/docs/_static/python-32.png b/docs/_static/python-32.png deleted file mode 100644 index c9a60f31c..000000000 Binary files a/docs/_static/python-32.png and /dev/null differ diff --git a/docs/_static/python-64.png b/docs/_static/python-64.png deleted file mode 100644 index 68ec727a6..000000000 Binary files a/docs/_static/python-64.png and /dev/null differ diff --git a/docs/api.rst b/docs/api.rst index 48d178aa8..a78c0feb1 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1,10 +1,6 @@ API Documentation ***************** - -.. contents:: Contents - :local: - jira package ============ diff --git a/docs/conf.py b/docs/conf.py index 8bd95769c..c4e8beef9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -10,16 +10,10 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import os -import sys - -import sphinx_rtd_theme - # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -sys.path.insert(0, os.path.abspath("..")) -from jira import __version__ # noqa +import jira as py_pkg # -- General configuration ----------------------------------------------------- @@ -33,6 +27,8 @@ "sphinx.ext.intersphinx", "sphinx.ext.napoleon", "sphinx.ext.viewcode", + # External + "sphinx_copybutton", ] intersphinx_mapping = { @@ -40,7 +36,7 @@ "requests": ("https://requests.readthedocs.io/en/latest/", None), "requests-oauthlib": ("https://requests-oauthlib.readthedocs.io/en/latest/", None), "ipython": ("https://ipython.readthedocs.io/en/stable/", None), - "pip": ("https://pip.readthedocs.io/en/stable/", None), + "pip": ("https://pip.pypa.io/en/stable/", None), } autodoc_default_options = { @@ -75,7 +71,7 @@ ] # Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] +# templates_path = [] # The suffix of source filenames. source_suffix = ".rst" @@ -87,7 +83,7 @@ master_doc = "index" # General information about the project. -project = "jira-python" +project = py_pkg.__name__ copyright = "2012, Atlassian Pty Ltd." # The version info for the project you're documenting, acts as replacement for @@ -95,9 +91,9 @@ # built documents. # # The short X.Y version. -version = __version__ +version = py_pkg.__version__ # The full version, including alpha/beta/rc tags. -release = __version__ +release = py_pkg.__version__ # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -138,16 +134,15 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = "sphinx_rtd_theme" +html_theme = "furo" # Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -html_theme_options = {"body_max_width": "100%"} +# further. For a list of options available for each theme, see the documentation. +# https://pradyunsg.me/furo/customisation/ +# html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] -html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". @@ -168,9 +163,9 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ["_static"] +# html_static_path = [] -html_style = "css/custom_width.css" +# html_style = "" # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. @@ -270,7 +265,7 @@ napoleon_google_docstring = True napoleon_numpy_docstring = False # Explicitly prefer Google style docstring napoleon_use_param = True # for type hint support - +napoleon_use_rtype = False # False so the return type is inline with the description. # -- Options for Texinfo output ------------------------------------------------ diff --git a/docs/contributing.rst b/docs/contributing.rst index 7acdb7592..0f8c39c23 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -37,60 +37,95 @@ Contributing Code Testing ******* -To test code run:: +Dev Container ++++++++++++++ - make test-all +We utilise Docker in order to generate a test Jira Server instance. -This will run the code in a virtual environment, and will test across the -versions of python which are installed. It will also install tox if it is -not already installed. +This can be run manually, or automated using VS Code Dev Containers: -Alternatively if you do not have make you can always run:: +#. Open the folder of the repository with VS Code +#. Ensure you have Docker running +#. Ensure you have the ``ms-azuretools.vscode-docker`` and ``ms-vscode-remote.remote-containers`` + extensions installed. +#. You should be able to do ``View >> Command Palette`` (or equivalent) and search for: + ``Remote-containers: Rebuild and Reopen in container``. - pip install tox +This will use the ``.devcontainer\Dockerfile`` as a base image with configurations +dictated by ``.devcontainer\devcontainer.json``. + +.. TIP:: + The Docker extension can be used to monitor the progress of the Jira server build, + it takes a while! The tests will only run once the server is up and reachable on: http://localhost:2990/jira + + +Running Tests ++++++++++++++ + +Using tox + +.. code-block:: bash + + python -m pip install pipx + pipx install tox tox +* Lint + - ``tox -e lint`` +* Run tests + - ``tox`` +* Run tests for one env only + - ``tox -e py38`` +* Specify what tests to run with pytest_ + - ``tox -e py39 -- tests/resources/test_attachment.py`` + - ``tox -e py38 -- -m allow_on_cloud`` (Run only the cloud tests) +* Debug tests with breakpoints by disabling the coverage plugin, with the ``--no-cov`` argument. + - Example for VSCode on Windows : + + .. code-block:: java + + { + "name": "Pytest", + "type": "python", + "request": "launch", + "python": ".tox\\py39\\Scripts\\python.exe", + "module": "pytest", + "env": { + "CI_JIRA_URL": "http://localhost:2990/jira", + "CI_JIRA_ADMIN": "admin", + "CI_JIRA_ADMIN_PASSWORD": "admin", + "CI_JIRA_USER": "jira_user", + "CI_JIRA_USER_FULL_NAME": "Newly Created CI User", + "CI_JIRA_USER_PASSWORD": "jira", + "CI_JIRA_ISSUE": "Task", + "PYTEST_TIMEOUT": "0", // Don't timeout + }, + "args": [ + // "-v", + "--no-cov", // running coverage affects breakpoints + "tests/resources/test_attachment.py" + ] + } + +.. _pytest: https://docs.pytest.org/en/stable/usage.html#specifying-tests-selecting-tests + + Issues and Feature Requests *************************** * Check to see if there's an existing issue/pull request for the bug/feature. All issues are at https://github.com/pycontribs/jira/issues and pull requests are at https://github.com/pycontribs/jira/pulls. -* If there isn't an existing issue there, please file an issue. The ideal - report includes: +* If there isn't an existing issue there, please file an issue. - * A description of the problem/suggestion. - * How to recreate the bug. - * If relevant, including the versions of your: + * An example template is provided for: - * Python interpreter (3.8, etc) - * jira-python - * Operating System and Version (Windows 7, OS X 10.10, Ubuntu 14.04, etc.) - * IPython if using jirashell - * Optionally of the other dependencies involved + * Bugs: https://github.com/pycontribs/jira/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml + * Features: https://github.com/pycontribs/jira/blob/main/.github/ISSUE_TEMPLATE/feature_request.yml * If possible, create a pull request with a (failing) test case demonstrating what's wrong. This makes the process for fixing bugs quicker & gets issues resolved sooner. - * Here is an template - :: - - Description: - - Python Interpreter: - jira-python: - OS: - IPython (Optional): - Other Dependencies: - - Steps To Reproduce: - 1. - 2. - 3. - ... - - Stack Trace: - Issues diff --git a/docs/examples.rst b/docs/examples.rst index 69277343b..2900fb3d0 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -1,9 +1,6 @@ Examples ******** -.. contents:: Contents - :local: - Here's a quick usage example: .. literalinclude:: ../examples/basic_use.py diff --git a/docs/index.rst b/docs/index.rst index 8c28f4d1f..49c77424d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,9 +1,3 @@ -.. jira-python documentation main file, created by - sphinx-quickstart on Thu May 3 17:01:50 2012. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - - Python Jira ########### Python library to work with Jira APIs diff --git a/docs/installation.rst b/docs/installation.rst index 47e1761f6..acb573fbd 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,20 +1,19 @@ Installation ************ -.. contents:: Contents - :local: - The easiest (and best) way to install jira-python is through `pip `_:: - $ pip install jira + pip install jira This will handle installation of the client itself as well as the requirements. If you're going to run the client standalone, we strongly recommend using a `virtualenv `_, -which pip can also set up for you:: +which pip can also set up for you + +.. code-block:: bash - $ pip -E jira_python install jira - $ workon jira_python + pip -E jira_python install jira + workon jira_python Doing this creates a private Python "installation" that you can freely upgrade, degrade or break without putting the critical components of your system at risk. @@ -23,7 +22,6 @@ Source packages are also available at PyPI: https://pypi.python.org/pypi/jira/ -.. _Dependencies: Dependencies ============ diff --git a/docs/jirashell.rst b/docs/jirashell.rst index de84fe21f..63f3a4482 100644 --- a/docs/jirashell.rst +++ b/docs/jirashell.rst @@ -5,9 +5,15 @@ There is no substitute for play. The only way to really know a service, API or p it, and bang your elbows -- trial and error. A REST design is especially well-suited for active exploration, and the ``jirashell`` script (installed automatically when you use pip) is designed to help you do exactly that. -Run it from the command line:: +.. code-block:: bash - $ jirashell -s https://jira.atlassian.com + pip install jira[cli] + +Run it from the command line + +.. code-block:: bash + + jirashell -s https://jira.atlassian.com *** Jira shell active; client is in 'jira'. Press Ctrl-D to exit. @@ -18,12 +24,17 @@ This is a specialized Python interpreter (built on IPython) that lets you explor Python code is acceptable input. The shell builds a ``JIRA`` client object for you (based on the launch parameters) and stores it in the ``jira`` object. -Try getting an issue:: +Try getting an issue + +.. code-block:: python In [1]: issue = jira.issue('JRA-1330') ``issue`` now contains a reference to an issue ``Resource``. To see the available properties and methods, hit the TAB -key:: +key + + +.. code-block:: python In [2]: issue. issue.delete issue.fields issue.id issue.raw issue.update diff --git a/docs/templates/.placeholder b/docs/templates/.placeholder deleted file mode 100644 index e69de29bb..000000000 diff --git a/setup.cfg b/setup.cfg index 6ac9f3a6b..fd6708fda 100644 --- a/setup.cfg +++ b/setup.cfg @@ -65,8 +65,10 @@ cli = ipython>=4.0.0 keyring docs = - Sphinx>=2.2.0 - sphinx_rtd_theme>=0.4.3 + sphinx>=5.0.0 + sphinx-copybutton + # HTML Theme + furo opt = filemagic>=1.6 PyJWT