[update] Updated docs and changelog post minor update

Changelog.rst

@@ -1,5 +1,17 @@
 Changelog
 =========
+
+1.3.6 (2022-11-22)
+-----------------------
+- MAJOR:
+    - none
+- MINOR:
+    - making UI simpler and more intuitive by a refactored OOP approach.
+    - data is now returned as a response object with its own parameters and methods.
+    - one-click method to every response object to convert it into a pandas DataFrame.
+- PATCH:
+    - various README improvements including better description of modules and their suggested use.
+
 iobis/pyobis dev
 -----------------------
 - MAJOR:

docs/checklist.rst

@@ -5,25 +5,22 @@ checklist module
 
 .. py:module:: pyobis.checklist
 
-.. autoclass:: ChecklistQuery
-
-A ChecklistQuery object for fetching checklist records.
+.. autoclass:: ChecklistResponse
 
 Usage
 #####
 
 .. code-block:: python
 
-    from pyobis.checklist import ChecklistQuery
+    from pyobis import checklist
 
-    query = ChecklistQuery()
-    data = query.search(args, **kwargs)
-    api_url = query.get_search_url()
+    query = checklist.list(taxonid=127405, **kwargs)
+    query.api_url  # Returns the API URL
+    query.to_pandas()  # Returns a pandas DataFrame object
 
 Methods:
 ########
 
-.. automethod:: ChecklistQuery.list
-.. automethod:: ChecklistQuery.redlist
-.. automethod:: ChecklistQuery.newest
-.. automethod:: ChecklistQuery.get_search_url
+.. autofunction:: list
+.. autofunction:: redlist
+.. autofunction:: newest

docs/dataset.rst

@@ -5,25 +5,24 @@ dataset module
 
 .. py:module:: pyobis.dataset
 
-.. autoclass:: DatasetQuery
-
-A DatasetQuery object for fetching dataset records.
+.. autoclass:: DatasetResponse
 
 Usage
 #####
 
 .. code-block:: python
 
-    from pyobis.dataset import DatasetQuery
+    from pyobis import dataset
+
+    query = dataset.search(args, **kwargs)  # Build the Query
+    query.execute()  # Execute the Query
+    query.data  # Returns the data
 
-    query = DatasetQuery()
-    data = query.search(args, **kwargs)
-    api_url = query.get_search_url()
+    # or build and execute at the same time
+    data = dataset.search(args, **kwargs).execute()
 
 Methods:
 ########
 
-.. automethod:: DatasetQuery.get
-.. automethod:: DatasetQuery.search
-.. automethod:: DatasetQuery.get_search_url
-.. automethod:: DatasetQuery.get_mapper_url
+.. autofunction:: get
+.. autofunction:: search

docs/index.rst

@@ -46,67 +46,75 @@ Taxa module
 
 .. code-block:: python
 
-    from pyobis.taxa import TaxaQuery
+    from pyobis import taxa
 
-    query = TaxaQuery()
+    query = taxa.search(scientificname="Mola mola")
+    query.execute()
+    query.data  # Returns the data
+    query.api_url  # Returns the API URL
+
+    data = taxa.search(scientificname="Mola mola").execute()
+    taxa.search(geometry="POLYGON((30.1 10.1, 10 20, 20 40, 40 40, 30.1 10.1))")
+    taxa.taxon(10332)
+    taxa.taxon(127405)
 
-    query.search(scientificname="Mola mola")
-    query.search(scientificname="Mola mola", offset=10)
-    query.search(geometry="POLYGON((30.1 10.1, 10 20, 20 40, 40 40, 30.1 10.1))")
-    query.taxon(10332)
-    query.taxon(127405)
-    query.get_search_url()
 
 Occurrence module
 #################
 
 .. code-block:: python
 
-    from pyobis.occurrences import OccQuery
+    from pyobis import occurrences
 
-    query = OccQuery()
+    query = occurrences.search(scientificname="Mola mola")
+    query.execute()
+    query.data  # Returns the data
+    query.api_url  # Returns the OBIS API URL
+    query.mapper_url  # Returns the OBIS Mapper URL
 
-    query.search(scientificname="Mola mola")
-    query.search(scientificname="Mola mola", offset=0, size=10)
-    query.search(
+    data = occurrences.search(scientificname="Mola mola", size=10).execute()
+    occurrences.search(
         geometry="POLYGON((30.1 10.1, 10 20, 20 40, 40 40, 30.1 10.1))", size=20
     )
-    query.get_mapper_url()
+
 
 Dataset module
 ##############
 
 .. code-block:: python
 
-    from pyobis.dataset import DatasetQuery
+    from pyobis import dataset
 
-    query = DatasetQuery()
+    query = dataset.search(scientificname=["Mola", "Abra", "Lanice", "Pectinaria"])
+    query.execute()
+    query.data  # Returns the data
+    query.api_url  # Returns the API URL
 
-    query.search(scientificname=["Mola", "Abra", "Lanice", "Pectinaria"])
-    query.get(id="ec9df3b9-3b2b-4d83-881b-27bcbcd57b95")
+    data = dataset.get(id="ec9df3b9-3b2b-4d83-881b-27bcbcd57b95").execute()
 
 Nodes module
 ############
 
 .. code-block:: python
 
-    from pyobis.nodes import NodesQuery
+    from pyobis import nodes
 
-    query = NodesQuery()
-
-    query.search(scientificname=["Mola", "Abra"])
-    query.get_search_url()
+    query = nodes.search(scientificname=["Mola", "Abra"])
+    query.execute()
+    query.data  # Returns the data
+    query.api_url  # Returns the API URL
 
 Checklist module
 ################
 
 .. code-block:: python
 
-    from pyobis.checklist import ChecklistQuery
-
-    query = ChecklistQuery()
+    from pyobis import checklist
 
-    query.list(scientificname="Cetacea")
+    query = checklist.list(scientificname="Cetacea")
+    query.execute()
+    query.data  # Returns the data
+    query.api_url  # Returns the OBIS API URL
 
 Meta
 ====
@@ -122,9 +130,6 @@ Meta
 
 
 
-
-
-
 Contents
 ========
 

docs/nodes.rst

@@ -5,25 +5,22 @@ nodes module
 
 .. py:module:: pyobis.nodes
 
-.. autoclass:: NodesQuery
-
-A NodesQuery object for fetching nodes records.
+.. autoclass:: NodesResponse
 
 Usage
 #####
 
 .. code-block:: python
 
-    from pyobis.nodes import NodesQuery
+    from pyobis import nodes
 
-    query = NodesQuery()
-    data = query.search(args, **kwargs)
-    api_url = query.get_search_url()
+    query = nodes.search(scientificname=["Mola", "Abra"], **kwargs)
+    query.execute()
+    query.data  # Returns the data
+    query.api_url  # Returns the API URL
 
 Methods:
 ########
 
-.. automethod:: NodesQuery.search
-.. automethod:: NodesQuery.activities
-.. automethod:: NodesQuery.get_search_url
-.. automethod:: NodesQuery.get_mapper_url
+.. autofunction:: search
+.. autofunction:: activities

docs/occurrences.rst

@@ -5,31 +5,34 @@ occurrences module
 
 .. py:module:: pyobis.occurrences
 
-.. autoclass:: OccQuery
-
-An OccQuery object for fetching occurrence records.
+.. autoclass:: OccResponse
 
 Usage
 #####
 
 .. code-block:: python
 
-    from pyobis.occurrences import OccQuery
+    from pyobis import occurrences
+
+    query = occurrences.search(scientificname="Mola mola")
+    query.execute()
+    query.data  # Returns the data
+    query.api_url  # Returns the OBIS API URL
+    query.mapper_url  # Returns the OBIS Mapper URL
 
-    query = OccQuery()
-    data = query.search(args, **kwargs)
-    api_url = query.get_search_url()
+    data = occurrences.search(scientificname="Mola mola", size=10).execute()
+    occurrences.search(
+        geometry="POLYGON((30.1 10.1, 10 20, 20 40, 40 40, 30.1 10.1))", size=20
+    )
 
 Methods:
 ########
 
-.. automethod:: OccQuery.search
-.. automethod:: OccQuery.get
-.. automethod:: OccQuery.grid
-.. automethod:: OccQuery.getpoints
-.. automethod:: OccQuery.point
-.. automethod:: OccQuery.tile
-.. automethod:: OccQuery.centroid
-.. automethod:: OccQuery.get_search_url
-.. automethod:: OccQuery.get_mapper_url
-.. automethod:: OccQuery.lookup_taxon
+.. autofunction:: search
+.. autofunction:: get
+.. autofunction:: grid
+.. autofunction:: getpoints
+.. autofunction:: point
+.. autofunction:: tile
+.. autofunction:: centroid
+.. autofunction:: lookup_taxon

docs/taxa.rst

@@ -5,25 +5,29 @@ taxa module
 
 .. py:module:: pyobis.taxa
 
-.. autoclass:: TaxaQuery
-
-A TaxaQuery object for fetching taxa records.
+.. autoclass:: TaxaResponse
 
 Usage
 #####
 
 .. code-block:: python
 
-    from pyobis.taxa import TaxaQuery
+    from pyobis import taxa
+
+    query = taxa.search(scientificname="Mola mola")
+    query.execute()
+    query.data  # Returns the data
+    query.api_url  # Returns the API URL
+    query.to_pandas()  # Returns a pandas DataFrame
 
-    query = TaxaQuery()
-    data = query.search(args, **kwargs)
-    api_url = query.get_search_url()
+    data = taxa.search(scientificname="Mola mola").execute()
+    taxa.search(geometry="POLYGON((30.1 10.1, 10 20, 20 40, 40 40, 30.1 10.1))")
+    taxa.taxon(10332)
+    taxa.taxon(127405)
 
 Methods:
 ########
 
-.. automethod:: TaxaQuery.search
-.. automethod:: TaxaQuery.taxon
-.. automethod:: TaxaQuery.annotations
-.. automethod:: TaxaQuery.get_search_url
+.. autofunction:: search
+.. autofunction:: taxon
+.. autofunction:: annotations

pyobis/checklist/__init__.py

@@ -1,7 +1,8 @@
-from .checklist import list, newest, redlist
+from .checklist import ChecklistResponse, list, newest, redlist
 
 __all__ = [
     "list",
     "redlist",
     "newest",
+    "ChecklistResponse",
 ]

pyobis/dataset/__init__.py

@@ -1,3 +1,3 @@
-from .dataset import get, search
+from .dataset import DatasetResponse, get, search
 
-__all__ = ["search", "get"]
+__all__ = ["search", "get", "DatasetResponse"]

pyobis/nodes/__init__.py

@@ -1,3 +1,3 @@
-from .nodes import activities, search
+from .nodes import NodesResponse, activities, search
 
-__all__ = ["search", "activities"]
+__all__ = ["search", "activities", "NodesResponse"]

pyobis/occurrences/__init__.py

@@ -1,4 +1,5 @@
 from .occurrences import (
+    OccResponse,
     centroid,
     get,
     getpoints,
@@ -18,4 +19,5 @@
     "lookup_taxon",
     "point",
     "centroid",
+    "OccResponse",
 ]

pyobis/taxa/__init__.py

@@ -1,3 +1,3 @@
-from .taxa import annotations, search, taxon
+from .taxa import TaxaResponse, annotations, search, taxon
 
-__all__ = ["search", "taxon", "annotations"]
+__all__ = ["search", "taxon", "annotations", "TaxaResponse"]