Merge pull request #11 from PH-KDX/devel

v0.4.1
PH-KDX · Jun 9, 2021 · bc82a37 · bc82a37
2 parents 194fa2d + c39c2ba
commit bc82a37
Show file tree

Hide file tree

Showing 6 changed files with 97 additions and 45 deletions.
diff --git a/docs/source/api/submodules/plan.rst b/docs/source/api/submodules/plan.rst
@@ -1,6 +1,31 @@
 Plan docs
 ====================
 
+.. csv-table:: Permitted plan return types
+   :header: "Plan format", "Key"
+   :widths: 25, 10
+
+   "Native dataclass format", "native"
+   "JSON formatted plan", "json"
+   "XML formatted plan", "xml"
+   "CSV formatted plan", "csv"
+   "PDF formatted plan", "pdf"
+   "Google Earth KML formatted plan", "kml"
+   "X-Plane FMS (8, 9 & 10) formatted plan", "xplane"
+   "X-Plane 11 formatted plan", "xplane11"
+   "FS2004/FS9 formatted plan", "fs9"
+   "FSX XML formatted plan", "fsx"
+   "Squawkbox formatted plan", "squawkbox"
+   "X-FMC formatted plan", "xfmc"
+   "PMDG rte formatted plan", "pmdg"
+   "Airbus X formatted plan", "airbusx"
+   "QualityWings formatted plan", "qualitywings"
+   "iFly 747 (.route) formatted plan", "ifly747"
+   "FlightGear formatted plan (version 2 XML)", "flightgear"
+   "TFDi Design 717 (version 1 XML)", "tfdi717"
+   "Infinite Flight", "infiniteflight"
+
+
 .. automodule:: flightplandb.submodules.plan
    :members:
    :undoc-members:
diff --git a/flightplandb/__init__.py b/flightplandb/__init__.py
@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 
 # Version of the flightplandb package
-__version__ = "0.3.1"
+__version__ = "0.4.1"
 
 from flightplandb.flightplandb import *  # noqa: F403, F401
 from flightplandb.datatypes import *  # noqa: F403, F401
diff --git a/flightplandb/flightplandb.py b/flightplandb/flightplandb.py
@@ -63,7 +63,7 @@ def __init__(
         self.url_base = url_base
 
     def _request(self, method: str,
-                 path: str, return_format="dict",
+                 path: str, return_format="native",
                  ignore_statuses: Optional[List] = None,
                  params: Optional[Dict] = None,
                  *args, **kwargs) -> Union[Dict, bytes]:
@@ -76,7 +76,7 @@ def _request(self, method: str,
         path : str
             The endpoint's path to which the request is being made
         return_format : str, optional
-            The API response format, defaults to ``"dict"``
+            The API response format, defaults to ``"native"``
         ignore_statuses : Optional[List], optional
             Statuses (together with 200 OK) which don't
             raise an HTTPError, defaults to None
@@ -90,7 +90,8 @@ def _request(self, method: str,
         Returns
         -------
         Union[Dict, bytes]
-            A ``dict`` if ``return_format`` is ``"dict"``, otherwise ``bytes``
+            A ``dataclass`` if ``return_format`` is ``"native"``,
+            otherwise ``bytes``
 
         Raises
         ------
@@ -102,12 +103,12 @@ def _request(self, method: str,
 
         format_return_types = {
             # if a dict is requested, the JSON will later be converted to that
-            "dict": "application/json",
+            "native": "application/vnd.fpd.v1+json",
             # otherwise, pure JSON will be returned
-            "json": "application/json",
-            "xml": "application/xml",
-            "csv": "text/csv",
-            "pdf": "application/pdf",
+            "json": "application/vnd.fpd.v1+json",
+            "xml": "application/vnd.fpd.v1+xml",
+            "csv": "text/vnd.fpd.export.v1.csv+csv",
+            "pdf": "application/vnd.fpd.export.v1.pdf",
             "kml": "application/vnd.fpd.export.v1.kml+xml",
             "xplane": "application/vnd.fpd.export.v1.xplane",
             "xplane11": "application/vnd.fpd.export.v1.xplane11",
@@ -147,19 +148,19 @@ def _request(self, method: str,
 
         resp = requests.request(method, urljoin(self.url_base, path),
                                 auth=HTTPBasicAuth(self.key, None),
-                                *args, **kwargs)
+                                headers=params, *args, **kwargs)
 
         status_handler(resp.status_code, ignore_statuses)
 
         self._header = resp.headers
 
-        if return_format == "dict":
+        if return_format == "native":
             return resp.json()
 
         return resp.text  # if the format is not a dict
 
     # and here go the specific non-paginated HTTP calls
-    def _get(self, path: str, return_format="dict",
+    def _get(self, path: str, return_format="native",
              ignore_statuses: Optional[List] = None,
              params: Optional[Dict] = None,
              *args, **kwargs) -> Union[Dict, bytes]:
@@ -170,7 +171,7 @@ def _get(self, path: str, return_format="dict",
         path : str
             The endpoint's path to which the request is being made
         return_format : str, optional
-            The API response format, defaults to ``"dict"``
+            The API response format, defaults to ``"native"``
         ignore_statuses : Optional[List], optional
             Statuses (together with 200 OK) which don't
             raise an HTTPError, defaults to None
@@ -184,7 +185,8 @@ def _get(self, path: str, return_format="dict",
         Returns
         -------
         Union[Dict, bytes]
-            A ``dict`` if ``return_format`` is ``"dict"``, otherwise ``bytes``
+            A ``dataclass`` if ``return_format`` is ``"native"``,
+            otherwise ``bytes``
         """
 
         # I HATE not being able to set empty lists as default arguments
@@ -200,7 +202,7 @@ def _get(self, path: str, return_format="dict",
                              *args, **kwargs)
         return resp
 
-    def _post(self, path: str, return_format="dict",
+    def _post(self, path: str, return_format="native",
               ignore_statuses: Optional[List] = None,
               params: Optional[Dict] = None,
               *args, **kwargs) -> Union[Dict, bytes]:
@@ -211,7 +213,7 @@ def _post(self, path: str, return_format="dict",
         path : str
             The endpoint's path to which the request is being made
         return_format : str, optional
-            The API response format, defaults to ``"dict"``
+            The API response format, defaults to ``"native"``
         ignore_statuses : Optional[List], optional
             Statuses (together with 200 OK) which don't
             raise an HTTPError, defaults to None
@@ -225,7 +227,8 @@ def _post(self, path: str, return_format="dict",
         Returns
         -------
         Union[Dict, bytes]
-            A ``dict`` if ``return_format`` is ``"dict"``, otherwise ``bytes``
+            A ``dataclass`` if ``return_format`` is ``"native"``,
+            otherwise ``bytes``
         """
         if not ignore_statuses:
             ignore_statuses = []
@@ -240,7 +243,7 @@ def _post(self, path: str, return_format="dict",
                              *args, **kwargs)
         return resp
 
-    def _patch(self, path: str, return_format="dict",
+    def _patch(self, path: str, return_format="native",
                ignore_statuses: Optional[List] = None,
                params: Optional[Dict] = None,
                *args, **kwargs) -> Union[Dict, bytes]:
@@ -251,7 +254,7 @@ def _patch(self, path: str, return_format="dict",
         path : str
             The endpoint's path to which the request is being made
         return_format : str, optional
-            The API response format, defaults to ``"dict"``
+            The API response format, defaults to ``"native"``
         ignore_statuses : Optional[List], optional
             Statuses (together with 200 OK) which don't
             raise an HTTPError, defaults to None
@@ -265,7 +268,8 @@ def _patch(self, path: str, return_format="dict",
         Returns
         -------
         Union[Dict, bytes]
-            A ``dict`` if ``return_format`` is ``"dict"``, otherwise ``bytes``
+            A ``dataclass`` if ``return_format`` is ``"native"``,
+            otherwise ``bytes``
         """
 
         if not ignore_statuses:
@@ -281,7 +285,7 @@ def _patch(self, path: str, return_format="dict",
                              *args, **kwargs)
         return resp
 
-    def _delete(self, path: str, return_format="dict",
+    def _delete(self, path: str, return_format="native",
                 ignore_statuses: Optional[List] = None,
                 params: Optional[Dict] = None,
                 *args, **kwargs) -> Union[Dict, bytes]:
@@ -292,7 +296,7 @@ def _delete(self, path: str, return_format="dict",
         path : str
             The endpoint's path to which the request is being made
         return_format : str, optional
-            The API response format, defaults to ``"dict"``
+            The API response format, defaults to ``"native"``
         ignore_statuses : Optional[List], optional
             Statuses (together with 200 OK) which don't
             raise an HTTPError, defaults to None
@@ -306,7 +310,8 @@ def _delete(self, path: str, return_format="dict",
         Returns
         -------
         Union[Dict, bytes]
-            A ``dict`` if ``return_format`` is ``"dict"``, otherwise ``bytes``
+            A ``dataclass`` if ``return_format`` is ``"native"``,
+            otherwise ``bytes``
         """
 
         if not ignore_statuses:

diff --git a/flightplandb/submodules/plan.py b/flightplandb/submodules/plan.py
@@ -16,7 +16,7 @@ def __init__(self, flightplandb):
         self._fp = flightplandb
 
     def fetch(self, id_: int,
-              return_format: str = "dict") -> Union[Plan, None, bytes]:
+              return_format: str = "native") -> Union[Plan, None, bytes]:
         # Underscore for id_ must be escaped as id\_ so sphinx shows the _.
         # However, this would raise W605. To fix this, a raw string is used.
         r"""
@@ -28,15 +28,16 @@ def fetch(self, id_: int,
         id\_ : int
             The ID of the flight plan to fetch
         return_format : str
-            The API response format, defaults to ``"dict"``
+            The API response format, defaults to ``"native"``.
+            Must be one of the keys in the table at the top of the page.
 
         Returns
         -------
         Union[Plan, None, bytes]
-            :class:`~flightplandb.datatypes.Plan` by default or if ``"dict"``
+            :class:`~flightplandb.datatypes.Plan` by default or if ``"native"``
             is specified as the ``return_format``.
 
-            ``bytes`` if a different format than ``"dict"`` was specified.
+            ``bytes`` if a different format than ``"native"`` was specified.
 
         Raises
         ------
@@ -49,13 +50,13 @@ def fetch(self, id_: int,
             return_format=return_format
         )
 
-        if return_format == "dict":
+        if return_format == "native":
             return Plan(**request)
 
         return request  # if the format is not a dict
 
     def create(self, plan: Plan,
-               return_format: str = "dict") -> Union[Plan, bytes]:
+               return_format: str = "native") -> Union[Plan, bytes]:
         """Creates a new flight plan.
 
         Requires authentication.
@@ -65,15 +66,16 @@ def create(self, plan: Plan,
         plan : Plan
             The Plan object to register on the website
         return_format : str
-            The API response format, defaults to ``"dict"``
+            The API response format, defaults to ``"native"``.
+            Must be one of the keys in the table at the top of the page.
 
         Returns
         -------
         Union[Plan, bytes]
-            :class:`~flightplandb.datatypes.Plan` by default or if ``"dict"``
+            :class:`~flightplandb.datatypes.Plan` by default or if ``"native"``
             is specified as the ``return_format``.
 
-            ``bytes`` if a different format than ``"dict"`` was specified.
+            ``bytes`` if a different format than ``"native"`` was specified.
 
         Raises
         ------
@@ -85,13 +87,13 @@ def create(self, plan: Plan,
         request = self._fp._post(
             "/plan/", return_format=return_format, json=plan._to_api_dict())
 
-        if return_format == "dict":
+        if return_format == "native":
             return Plan(**request)
 
         return request
 
     def edit(self, plan: Plan,
-             return_format: str = "dict") -> Union[Plan, bytes]:
+             return_format: str = "native") -> Union[Plan, bytes]:
         """Edits a flight plan linked to your account.
 
         Requires authentication.
@@ -101,15 +103,16 @@ def edit(self, plan: Plan,
         plan : Plan
             The new Plan object to replace the old one associated with that ID
         return_format : str
-            The API response format, defaults to ``"dict"``
+            The API response format, defaults to ``"native"``.
+            Must be one of the keys in the table at the top of the page.
 
         Returns
         -------
         Union[Plan, bytes]
-            :class:`~flightplandb.datatypes.Plan` by default or if ``"dict"``
+            :class:`~flightplandb.datatypes.Plan` by default or if ``"native"``
             is specified as the ``return_format``.
 
-            ``bytes`` if a different format than ``"dict"`` was specified.
+            ``bytes`` if a different format than ``"native"`` was specified.
 
         Raises
         ------
@@ -123,7 +126,7 @@ def edit(self, plan: Plan,
         plan_data = plan._to_api_dict()
         request = self._fp._patch(f"/plan/{plan_data['id']}", json=plan_data)
 
-        if return_format == "dict":
+        if return_format == "native":
             return Plan(**request)
 
         return request
@@ -258,7 +261,7 @@ def unlike(self, id_: int) -> bool:
         return True
 
     def generate(self, gen_query: GenerateQuery,
-                 return_format: str = "dict") -> Union[Plan, bytes]:
+                 return_format: str = "native") -> Union[Plan, bytes]:
         """Creates a new flight plan using the route generator.
 
         Requires authentication.
@@ -268,15 +271,16 @@ def generate(self, gen_query: GenerateQuery,
         gen_query : GenerateQuery
             A dataclass with options for flight plan generation
         return_format : str
-            The API response format, defaults to ``"dict"``
+            The API response format, defaults to ``"native"``.
+            Must be one of the keys in the table at the top of the page.
 
         Returns
         -------
         Union[Plan, bytes]
-            Plan by default or if ``"dict"`` is specified as
+            Plan by default or if ``"native"`` is specified as
             the ``return_format``.
 
-            Bytes if a different format than ``"dict"`` was specified
+            Bytes if a different format than ``"native"`` was specified
         """
 
         return Plan(

diff --git a/setup.py b/setup.py
@@ -1,12 +1,30 @@
 #!/usr/bin/env python
 from setuptools import setup, find_packages
+import codecs
+import os.path
 
 with open("README.md", "r") as fh:
     long_description = fh.read()
 
+
+def read(rel_path):
+    here = os.path.abspath(os.path.dirname(__file__))
+    with codecs.open(os.path.join(here, rel_path), 'r') as fp:
+        return fp.read()
+
+
+def get_version(rel_path):
+    for line in read(rel_path).splitlines():
+        if line.startswith('__version__'):
+            delim = '"' if '"' in line else "'"
+            return line.split(delim)[1]
+    else:
+        raise RuntimeError("Unable to find version string.")
+
+
 setup(
     name="flightplandb",
-    version="0.4.0",
+    version=get_version("flightplandb/__init__.py"),
     author="PH-KDX",
     url="https://github.com/PH-KDX/flightplandb-py/",
     project_urls={