Merge branch 'master' into housekeeping

docs/conf.py

@@ -47,15 +47,19 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.viewcode"]
+extensions = [
+    "recommonmark",
+    "sphinx.ext.autodoc",
+    "sphinx_autodoc_typehints",
+    "sphinx_markdown_tables",
+    "sphinx_rtd_theme",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
 # The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-source_suffix = [".rst", ".md"]
+source_suffix = {".rst": "restructuredtext", ".md": "markdown"}
 
 
 # The master toctree document.
@@ -66,22 +70,23 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+# language = None
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = [
     "_build",
-    "*.csv",
+    "*env*",
     "samples/*",
     "Thumbs.db",
     ".DS_Store",
-    "*env*",
     "libs/*",
-    "*.xml",
     "input/*",
     "output/*",
+    "*.csv",
+    "*.xlsx",
+    "*.xml",
 ]
 
 # The name of the Pygments (syntax highlighting) style to use.
@@ -93,7 +98,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "default"
+html_theme = "sphinx_rtd_theme"
 
 # 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
@@ -186,11 +191,19 @@
     )
 ]
 
+# related documentation
+intersphinx_mapping = {
+    "python": ("https://python.readthedocs.io/en/latest/", None),
+    "isogeo-api-pysdk": ("https://isogeo-api-pysdk.readthedocs.io/en/latest/", None),
+    "requests": ("https://requests.readthedocs.io/en/latest/", None),
+    "oauthlib": ("https://oauthlib.readthedocs.io/en/latest/", None),
+    "requests_oauthlib": ("https://requests-oauthlib.readthedocs.io/en/latest/", None),
+}
 
 # -- Options for Epub output -------------------------------------------------
 
 # Bibliographic Dublin Core info.
-epub_title = project
+# epub_title = project
 
 # The unique identifier of the text. This can be a ISBN number
 # or the project homepage.
@@ -202,15 +215,15 @@
 # epub_uid = ''
 
 # A list of files that should not be packed into the epub file.
-epub_exclude_files = ["search.html"]
+# epub_exclude_files = ["search.html"]
 
 
 # -- Extension configuration -------------------------------------------------
 
 # -- Options for todo extension ----------------------------------------------
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = True
+# todo_include_todos = True
 
 
 # -- Options for Sphinx API doc ----------------------------------------------

docs/index.rst

@@ -1,8 +1,3 @@
-.. Isogeo - XLSX Exporter documentation master file, created by
-   sphinx-quickstart on Wed Dec  5 16:55:53 2018.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Welcome to Isogeo - XLSX Exporter's documentation!
 ==================================================
 

docs/usage.md

@@ -0,0 +1,146 @@
+# Usage
+
+IsogeoToXlsx processes a [Isogeo Search as defined in the Isogeo Python SDK](https://isogeo-api-pysdk.readthedocs.io/en/latest/_apidoc/isogeo_pysdk.models.metadata_search.html). You need to perform an authenticated search before using the export package.
+
+## Basic workflow
+
+1. Store your secret as environment variables (using an `.env` file for example)
+2. Authenticate
+
+    ```python
+    # import
+    from isogeo_pysdk import Isogeo
+    # API client
+    isogeo = Isogeo(
+        auth_mode="group",
+        client_id=ISOGEO_API_GROUP_CLIENT_ID,
+        client_secret=ISOGEO_API_GROUP_CLIENT_SECRET,
+        auto_refresh_url="{}/oauth/token".format(ISOGEO_ID_URL),
+        platform=ISOGEO_PLATFORM,
+    )
+
+    # getting a token
+    isogeo.connect()
+    ```
+
+3. Make a search:
+
+    ```python
+    search = isogeo.search(include="all", page_size=100)
+    # close session
+    isogeo.close()
+    ```
+
+4. Export:
+
+    ```python
+    # import
+    from isogeotoxlsx import Isogeo2xlsx
+
+    # instanciate the final workbook
+    out_workbook = Isogeo2xlsx(
+        lang=isogeo.lang,
+        url_base_edit=isogeo.app_url,
+        url_base_view=isogeo.oc_url,
+        write_only=True
+    )
+    # add needed worksheets
+    out_workbook.set_worksheets(
+        auto=search.tags.keys(),  # create the relevant sheets according to the metadata types
+    )
+
+    # map search results and store method
+    for md in map(Metadata.clean_attributes, search.results):
+        out_workbook.store_metadatas(md)
+
+    # save as file
+    out_workbook.save("./isogeo_export_to_xlsx.xlsx")
+
+    # close properly
+    out_worbook.close()
+    ```
+
+---
+
+## Advanced
+
+### Add a dashboard sheet
+
+1. Set the `dashboard` bool argument to True
+2. After the export, launch the analisis.
+
+```python
+# import
+from isogeotoxlsx import Isogeo2xlsx
+# instanciate the final workbook
+out_workbook = Isogeo2xlsx(
+    lang=isogeo.lang,
+    url_base_edit=isogeo.app_url,
+    url_base_view=isogeo.oc_url,
+    write_only=True
+)
+# add needed worksheets
+out_workbook.set_worksheets(
+    auto=search.tags.keys(),  # create the relevant sheets according to the metadata types
+    dashboard=True  # set the dashboard to True
+)
+
+# map search results and store method
+for md in map(Metadata.clean_attributes, search.results):
+    out_workbook.store_metadatas(md)
+
+# launch analisis
+out_workbook.launch_analisis()
+
+# save as file
+out_workbook.save("./isogeo_export_to_xlsx.xlsx")
+
+# close properly
+out_worbook.close()
+```
+
+### Auto-tune the sheets
+
+After the export, launch the spreadsheets auto-tunning:
+
+```python
+# apply filters
+out_workbook.tunning_worksheets()
+```
+
+### Save the output as memory-like object
+
+For certain use cases (read-only filesystems, email's attachment...), it's preferable to not save the file on the OS and use it as memory-like object.
+
+```python
+# import
+from io import BytesIO
+from isogeotoxlsx import Isogeo2xlsx
+
+# instanciate the final workbook
+out_workbook = Isogeo2xlsx(
+    lang=isogeo.lang,
+    url_base_edit=isogeo.app_url,
+    url_base_view=isogeo.oc_url,
+    write_only=True
+)
+# add needed worksheets
+out_workbook.set_worksheets(
+    auto=search.tags.keys(),  # create the relevant sheets according to the metadata types
+)
+
+# map search results and store method
+for md in map(Metadata.clean_attributes, search.results):
+    out_workbook.store_metadatas(md)
+
+# or save in a memory object
+mem_virtual_workbook = BytesIO()
+out_workbook.save(mem_virtual_workbook)
+out_worbook.close()
+
+# DO YOUR STUFF
+
+# close properly
+mem_virtual_workbook.close()
+
+```

isogeotoxlsx/__about__.py

@@ -19,7 +19,7 @@
 __summary__ = "Toolbelt to export metadata from the Isogeo REST API into Microsoft Excel workbooks (.xlsx)."
 __uri__ = "https://pypi.org/project/isogeo-export-xl/"
 
-__version__ = "1.2.3"
+__version__ = "1.2.4"
 
 __author__ = "Isogeo"
 __email__ = "contact@isogeo.com"

isogeotoxlsx/isogeo2xlsx.py

@@ -56,7 +56,12 @@ class Isogeo2xlsx(Workbook):
     """
 
     def __init__(
-        self, lang: str = "FR", url_base_edit: str = "", url_base_view: str = ""
+        self,
+        lang: str = "FR",
+        url_base_edit: str = "",
+        url_base_view: str = "",
+        # additional
+        **kwargs,
     ):
         """Instanciating the output workbook.
 
@@ -797,11 +802,12 @@ def tunning_worksheets(self, excluded_sheets: tuple = ("dashboard",)):
     isogeo.connect()
 
     # misc
+    print("App used: {}".format(isogeo.app_properties.name))
     METADATA_TEST_FIXTURE_UUID = environ.get("ISOGEO_FIXTURES_METADATA_COMPLETE")
     WORKGROUP_TEST_FIXTURE_UUID = environ.get("ISOGEO_WORKGROUP_TEST_UUID")
 
     search = isogeo.search(
-        whole_results=0,
+        whole_results=1,
         # query="owner:{}".format(WORKGROUP_TEST_FIXTURE_UUID),
         include="all",
     )
@@ -812,7 +818,7 @@ def tunning_worksheets(self, excluded_sheets: tuple = ("dashboard",)):
 
     # instanciate th final workbook
     out_workbook = Isogeo2xlsx(
-        lang=isogeo.lang, url_base_edit=isogeo.app_url, url_base_view=isogeo.oc_url
+        lang=isogeo.lang, url_base_edit=isogeo.app_url, url_base_view=isogeo.oc_url,
     )
     # add needed worksheets
     out_workbook.set_worksheets(auto=search.tags.keys(), attributes=1, dashboard=1)

isogeotoxlsx/utils/formatter.py

@@ -55,10 +55,7 @@ class Formatter(object):
     """
 
     def __init__(
-        self,
-        lang="FR",
-        output_type="Excel",
-        default_values=("NR", "1970-01-01T00:00:00+00:00"),
+        self, lang="FR", output_type="Excel",
     ):
         # locale
         self.lang = lang.lower()
@@ -71,14 +68,31 @@ def __init__(
 
         # store params and imports as attributes
         self.output_type = output_type.lower()
-        self.defs = default_values
         self.isogeo_tr = IsogeoTranslator(lang).tr
 
     # ------------ Metadata sections formatter --------------------------------
     def conditions(self, md_cgus: list) -> list:
         """Render input metadata CGUs as a new list.
 
-        :param dict md_cgus: input dictionary extracted from an Isogeo metadata
+        :param list md_cgus: list of conditions extracted from an Isogeo metadata
+
+        :rtype: list
+
+        :Example:
+
+        .. code-block:: python
+
+
+            # make a search including conditions
+            search = isogeo.search(include=("conditions",))
+
+            # parse results
+            for md in search.results:
+                # load metadata as object
+                md = Metadata.clean_attributes(md)
+
+                # format conditions
+                cgus_out = formatter.conditions(md.conditions)
         """
         cgus_out = []
         for c_in in md_cgus:

isogeotoxlsx/utils/stats.py

@@ -44,10 +44,7 @@
 
 
 class Stats(object):
-    """Perform statistics calculations and make Excel charts.
-
-    :param str lang: selected language for output
-    """
+    """Perform statistics calculations and make Excel charts."""
 
     li_data_formats = []
     li_dates_md_created = []

tests/test_export_xlsx.py

@@ -68,7 +68,9 @@ def setUp(self):
         )
 
         # target class instanciation
-        self.out_wb = Isogeo2xlsx(lang="FR", url_base_edit="https://app.isogeo.com")
+        self.out_wb = Isogeo2xlsx(
+            lang="FR", url_base_edit="https://app.isogeo.com", write_only=True
+        )
 
     def tearDown(self):
         """Executed after each test."""