Merge pull request #17 from PH-KDX/feature

v0.6.0
PH-KDX · May 19, 2022 · 420a4f4 · 420a4f4
2 parents 9657eae + 871d1da
commit 420a4f4
Show file tree

Hide file tree

Showing 50 changed files with 3,360 additions and 2,914 deletions.
diff --git a/.github/workflows/test_and_lint.yml b/.github/workflows/test_and_lint.yml
@@ -9,19 +9,19 @@ jobs:
       - name: Check out source repository
         uses: actions/checkout@v2
       - name: Set up Python environment
-        uses: actions/setup-python@v1
+        uses: actions/setup-python@v2
         with:
-          python-version: "3.7"
+          python-version: "3.9"
       - name: flake8 Lint
         uses: py-actions/flake8@v1
         with:
-          max-line-length: "80"
+          max-line-length: "120"
 
   # but we do want to run unittests on many python versions
   unittests:
     strategy:
       matrix:
-        python-version: [ '3.7', '3.8', '3.9' ]
+        python-version: [ '3.7', '3.8', '3.9', '3.10' ]
     runs-on: ubuntu-latest
 
     name: Unit tests, Python ${{ matrix.python-version }}
@@ -30,10 +30,10 @@ jobs:
       - name: Check out source repository
         uses: actions/checkout@v2
       - name: Set up Python environment
-        uses: actions/setup-python@v1
+        uses: actions/setup-python@v2
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install packages
-        run: python -m pip install .
+        run: python -m pip install .[test]
       - name: Run unittests
-        run: python -m unittest
+        run: python -m pytest tests
diff --git a/.gitignore b/.gitignore
@@ -21,3 +21,4 @@ docs/build
 ignore/
 
 venv
+**/*.swp
diff --git a/README.md b/README.md
@@ -14,20 +14,12 @@ This is a Python 3 wrapper for the [Flight Plan Database API](https://flightplan
 
 For more information on Flight Plan Database, see their excellent [About page](https://flightplandatabase.com/about).
 
-## API
-All the API commands can be called via the `flightplandb.FlightPlanDB` class.
-It is organized into subsections as specified in the docs; i.e. `FlightPlanDB.plan` has all the plan API commands.
-
-## Data Types
-All datatypes can be found in `flightplandb.datatypes`.
-
-## Exceptions
-All exceptions can be found in `flightplandb.exceptions`.
-
 ## Documentation
 The documentation for this library can be found on readthedocs.io [here](https://flightplandb-py.readthedocs.io/).
 
 ## Installation
 The library can be installed from PyPi using `pip install flightplandb`;
-the installation page link is [here](https://pypi.org/project/flightplandb/). For more details on
-installing bleeding-edge versions, see the Installation section of the documentation.
+the PyPi installation page link is [here](https://pypi.org/project/flightplandb/). For more details, see the Installation section of the documentation.
+
+## Changelog
+Before upgrading to a newer version, please read the appropriate changelog for your upgrade [here](https://flightplandb-py.readthedocs.io/en/stable/user/changelog.html).
diff --git a/docs/source/_static/css/colourscheme.css b/docs/source/_static/css/colourscheme.css
@@ -3103,6 +3103,9 @@
         border-color: rgb(27, 84, 122);
         background-color: rgb(32, 35, 36); background-image: none;
     }
+    html.writer-html4 .rst-content dl:not(.docutils) .descclassname, html.writer-html4 .rst-content dl:not(.docutils) .descname, html.writer-html4 .rst-content dl:not(.docutils) .sig-name, html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .descclassname, html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .descname, html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .sig-name {
+    	color: rgb(255, 255, 255);
+    }
     span[id*="MathJax-Span"] {
         color: rgb(192, 186, 178);
     }

diff --git a/docs/source/api/api.rst b/docs/source/api/api.rst
@@ -1,14 +1,5 @@
-API docs
+API
 ====================
 
-.. automodule:: flightplandb
+.. automodule:: flightplandb.api
    :members:
-   :undoc-members:
-   :show-inheritance:
-
-.. toctree::
-   :maxdepth: 5
-
-   flightplandb
-   datatypes
-   exceptions
diff --git a/docs/source/api/datatypes.rst b/docs/source/api/datatypes.rst
@@ -1,4 +1,4 @@
-Datatypes docs
+Datatypes
 ====================
 
 .. automodule:: flightplandb.datatypes

diff --git a/docs/source/api/exceptions.rst b/docs/source/api/exceptions.rst
@@ -1,4 +1,4 @@
-Exceptions docs
+Exceptions
 ====================
 
 .. automodule:: flightplandb.exceptions

diff --git a/docs/source/api/flightplandb.rst b/docs/source/api/flightplandb.rst
diff --git a/docs/source/api/internal.rst b/docs/source/api/internal.rst
@@ -0,0 +1,6 @@
+Internal functions
+====================
+
+.. automodule:: flightplandb.internal
+   :members:
+   :undoc-members:
diff --git a/docs/source/api/main.rst b/docs/source/api/main.rst
@@ -0,0 +1,20 @@
+API reference
+====================
+
+.. automodule:: flightplandb
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. toctree::
+   :maxdepth: 5
+
+   api
+   nav
+   plan
+   tags
+   user
+   weather
+   datatypes
+   exceptions
+   internal
diff --git a/docs/source/api/submodules/nav.rst → docs/source/api/nav.rst b/docs/source/api/submodules/nav.rst → docs/source/api/nav.rst
@@ -1,6 +1,6 @@
-Nav docs
+Nav
 ====================
 
-.. automodule:: flightplandb.submodules.nav
+.. automodule:: flightplandb.nav
    :members:
    :undoc-members:
diff --git a/docs/source/api/submodules/plan.rst → docs/source/api/plan.rst b/docs/source/api/submodules/plan.rst → docs/source/api/plan.rst
@@ -1,7 +1,8 @@
-Plan docs
+Plan
 ====================
 
-.. csv-table:: Permitted plan return types
+.. _permitted-return-types:
+.. csv-table:: Table of permitted plan return types
    :header: "Plan format", "Key"
    :widths: 25, 10
 
@@ -26,6 +27,6 @@ Plan docs
    "Infinite Flight", "infiniteflight"
 
 
-.. automodule:: flightplandb.submodules.plan
+.. automodule:: flightplandb.plan
    :members:
    :undoc-members:
diff --git a/docs/source/api/submodules/tags.rst b/docs/source/api/submodules/tags.rst
diff --git a/docs/source/api/submodules/user.rst b/docs/source/api/submodules/user.rst
diff --git a/docs/source/api/submodules/weather.rst b/docs/source/api/submodules/weather.rst
diff --git a/docs/source/api/tags.rst b/docs/source/api/tags.rst
@@ -0,0 +1,6 @@
+Tags
+====================
+
+.. automodule:: flightplandb.tags
+   :members:
+   :undoc-members:
diff --git a/docs/source/api/user.rst b/docs/source/api/user.rst
@@ -0,0 +1,6 @@
+User
+====================
+
+.. automodule:: flightplandb.user
+   :members:
+   :undoc-members:
diff --git a/docs/source/api/weather.rst b/docs/source/api/weather.rst
@@ -0,0 +1,6 @@
+Weather
+=====================
+
+.. automodule:: flightplandb.weather
+   :members:
+   :undoc-members:
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -21,7 +21,9 @@
 author = 'PH-KDX'
 
 # The full version, including alpha/beta/rc tags
-release = '0.5.0'
+release = '0.6.0'
+# readthedocs.io insists on the version field being filled for epub builds
+version = release
 
 
 # -- General configuration ---------------------------------------------------
@@ -41,7 +43,6 @@
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
-add_module_names = False
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -16,7 +16,7 @@ If you're new, check out the :doc:`user/introduction` or :doc:`user/quickstart`
 
    user/userdocs
 
-   api/api
+   api/main
 
 
 

diff --git a/docs/source/user/changelog.rst b/docs/source/user/changelog.rst
@@ -0,0 +1,9 @@
+Changelog
+--------------------
+
+0.6.0
+^^^^^^^^^^^^^^^^^^^^
+This is a complete rewrite of the library, which moves functions out of classes.
+This does have the side effect of requiring a key to be passed into every authenticated request,
+instead of being passed into a class once on initialisation. The rewrite also incorporates
+several small bugfixes, and changes the test environment from unittest to pytest.
diff --git a/docs/source/user/introduction.rst b/docs/source/user/introduction.rst
@@ -14,8 +14,6 @@ Prerequisites
 FlightplanDB-py works with Python 3.7 or higher. Python 3.6 or
 lower is not supported due to dataclasses, which were introduced with
 `PEP 557 <https://www.python.org/dev/peps/pep-0557/>`_, being used in the library.
-These instructions were written with Debian in mind, so you might have tweak them
-a little to get everything working on your machine.
 
 Installation
 ^^^^^^^^^^^^^^^^^^^^
@@ -25,11 +23,11 @@ The easiest way to install the library is from PyPi, by running
 
   $ pip install flightplandb
 
-Or, if you like living dangerously, install the devel branch directly from the GitHub repo:
+Or, if you prefer, install the directly from the GitHub repo:
 
 .. code-block:: console
 
-  $ pip install https://github.com/PH-KDX/flightplandb-py/archive/devel.zip
+  $ pip install https://github.com/PH-KDX/flightplandb-py/archive/main.zip
 
 after which the package and its dependencies are installed.
 
@@ -42,16 +40,22 @@ Start by going to
 your project's working directory.
 Create a virtual environment called, for example, ``foo`` as follows:
 
-.. code-block:: console
+.. code-block:: bash
 
   $ python3 -m venv foo
 
-then when you want to use it, activate it with
+then when you want to use it, activate it on Linux or macOS with
 
-.. code-block:: console
+.. code-block:: bash
 
   $ source foo/activate/bin
 
+or on Windows with
+
+.. code-block:: dosbatch
+
+  $ foo\Scripts\activate.bat
+
 after which you can install the library as described in `Installation <#installation>`_.
 
 
@@ -63,34 +67,37 @@ To test if the package has correctly installed, open a Python shell
 .. code-block:: python3
 
    import flightplandb
-   flightplandb.FlightPlanDB().ping()
+   flightplandb.api.ping()
 
 which should return
 ``StatusResponse(message='OK', errors=None)``
 if all has gone well.
 
 
+.. _request-limits:
+
 Request Limits
 ^^^^^^^^^^^^^^^^^^^^
 API requests are rate limited on a 24 hour rolling basis to ensure fair access to all users.
 If you reach your daily limit, a
 :class:`~flightplandb.exceptions.TooManyRequestsException()` will be raised on
 your requests. To check your limit and used requests, look at the output of
-:meth:`~flightplandb.FlightPlanDB.limit_cap` and
-:meth:`~flightplandb.FlightPlanDB.limit_used` respectively.
-These calls, together with :meth:`~flightplandb.FlightPlanDB.ping()`, will not increment your request counter.
+:meth:`flightplandb.api.limit_cap()` and
+:meth:`flightplandb.api.limit_used()` respectively.
+These calls, together with :meth:`flightplandb.api.ping()`, will not increment your request counter.
 
 The limit for unauthenticated users is IP-based, and is currently set to 100.
 The limit for authenticated users is key-based, and is currently set to 2500.
 
 
+.. _authentication:
+
 Authentication
 ^^^^^^^^^^^^^^^^^^^^
 Whilst many parts of the API are publicly accessible, some endpoints require
 authentication with an API access key, which is an alphanumeric string such as
 ``VtF93tXp5IUZE307kPjijoGCUtBq4INmNTS4wlRG``. If provided, this key must be
-specified when initiating a :meth:`~flightplandb.FlightPlanDB` class instance,
-using the ``key`` argument.
+passed into every authenticated request, using the ``key`` argument.
 
 To get an API key, visit your Flight Plan Database
 `account settings <https://flightplandatabase.com/settings>`_ page.
@@ -101,9 +108,4 @@ provide valid authentication credentials on these endpoints will result in an
 :class:`~flightplandb.exceptions.UnauthorizedException()` being raised. You are responsible
 for maintaining the security of your private API key, which gives near full access to
 your Flight Plan Database account. If your key is exposed, please use
-:meth:`~flightplandb.FlightPlanDB.revoke()` to revoke your key manually.
-
-
-Further information
-^^^^^^^^^^^^^^^^^^^^
-A good video on the usage of the library can be found `here <https://youtu.be/dQw4w9WgXcQ>`_.
+:meth:`flightplandb.api.revoke()` to revoke your key manually.