Skip to content
Permalink
Browse files

Update documentation

  • Loading branch information...
J535D165 committed Dec 2, 2018
1 parent 07e30c5 commit 3156e4c93af69453cdf4a2a52cd568a8c4120fe5
Showing with 134 additions and 82 deletions.
  1. +7 −6 README.rst
  2. +109 −75 cbsodata.py
  3. +18 −1 docs/conf.py
@@ -129,14 +129,14 @@ file system.
>>> data = cbsodata.get_data('82070ENG', dir="dir_to_save_data")
Use other catalogs
~~~~~~~~~~~~~~~~~~
Catalogs (dataderden)
~~~~~~~~~~~~~~~~~~~~~

There are multiple ways to retrieve data from catalogs other than
'opendata.cbs.nl'. The code below shows 3 different ways to retrieve data from
the catalog 'dataderden.cbs.nl' (known from Iv3).

Module level.
On module level.

.. code:: python
@@ -146,7 +146,7 @@ Module level.
# get dataset 47003NED
cbsodata.get_data('47003NED')
Context managers.
With context managers.

.. code:: python
@@ -156,7 +156,7 @@ Context managers.
# get dataset 47003NED
cbsodata.get_data('47003NED')
Function argument.
As a function argument.

.. code:: python
@@ -168,7 +168,8 @@ Function argument.
Pandas users
~~~~~~~~~~~~

Convert the result into a pandas DataFrame.
The package works well with Pandas. Convert the result easily into a pandas
DataFrame with the code below.

.. code:: python
@@ -108,7 +108,7 @@ def _get_catalog_url(url):


def _get_table_url(table_id, catalog_url=None):
"""Create a table url for the given table indentifier."""
"""Create a table url for the given table identifier."""

if catalog_url is None:
_catalog_url = options.catalog_url
@@ -183,11 +183,15 @@ def _save_data(data, dir, metadata_name):
def _filters(query):
"""Filter rows with a CBS-style query.
:param query: The rows to return.
:type query: str
Parameters
----------
query : str
The rows to return.
:returns: URL parameter
:rtype: str
Returns
-------
str
Filter parameter for URL
"""

return query
@@ -196,11 +200,15 @@ def _filters(query):
def _select(select):
"""Select columns.
:param select: The columns to return.
:type select: str, list
Parameters
----------
select : str
The columns to return.
:returns: URL parameter
:rtype: str
Returns
-------
str
Select parameter for URL
"""

if isinstance(select, list):
@@ -211,23 +219,28 @@ def _select(select):

def download_data(table_id, dir=None, typed=False, select=None, filters=None,
catalog_url=None):
"""
Download the CBS data and metadata.
:param table_id: The indentifier of the table.
:param dir: Folder to save data to. If not given, data is not stored on
disk.
:param typed: Return a typed data table. Default False.
:param select: Column label or list of column labels to return.
:param filters: Return only rows that agree on the filter.
:type table_id: str
:type dir: str
:type typed: bool
:type select: list
:type filters: str
:returns: The requested data.
:rtype: list
"""Download the CBS data and metadata.
Parameters
----------
table_id : str
The identifier of the table.
dir : str
Folder to save data to. If not given, data is not stored on
disk.
typed : bool
Return a typed data table. Default False.
select : str, list
Column label or list of column labels to return.
filters : str
Return only rows that agree on the filter.
catalog_url : str
The url of the catalog. Default "opendata.cbs.nl".
Returns
-------
list
A dictionary with the (meta)data of the table
"""

_catalog_url = _get_catalog_url(catalog_url)
@@ -267,17 +280,21 @@ def download_data(table_id, dir=None, typed=False, select=None, filters=None,


def get_table_list(select=None, filters=None, catalog_url=None):
"""
Get a list with the available tables.
:param select: Column label or list of column labels to return.
:param filters: Return only rows that agree on the filter.
:type select: list
:type filters: str
:returns: Information about the available tables (list of dictionaries)
:rtype: list
"""Get a list with the available tables.
Parameters
----------
select : list, str
Column label or list of column labels to return.
filters : str
Return only rows that agree on the filter.
catalog_url : str
The url of the catalog. Default "opendata.cbs.nl".
Returns
-------
list
A list with the description of each table in the catalog.
"""

# http://opendata.cbs.nl/ODataCatalog/Tables?$format=json&$filter=ShortTit
@@ -318,14 +335,19 @@ def get_table_list(select=None, filters=None, catalog_url=None):


def get_info(table_id, catalog_url=None):
"""
Get information about a table.
:param table_id: The indentifier of the table.
:type table_id: str
:returns: Table information
:rtype: dict
"""Get information about a table.
Parameters
----------
table_id : str
The identifier of the table.
catalog_url : str
The url of the catalog. Default "opendata.cbs.nl".
Returns
-------
dict
Table information
"""

info_list = _download_metadata(
@@ -341,16 +363,21 @@ def get_info(table_id, catalog_url=None):


def get_meta(table_id, name, catalog_url=None):
"""
Get the metadata of a table.
:param table_id: The indentifier of the table.
:param name: The name of the metadata (for example DataProperties).
:type table_id: str
:type name: str
:returns: list with metadata (dict type)
:rtype: list
"""Get the metadata of a table.
Parameters
----------
table_id : str
The identifier of the table.
name : str
The name of the metadata (for example DataProperties).
catalog_url : str
The url of the catalog. Default "opendata.cbs.nl".
Returns
-------
list
A list with metadata (dict type)
"""

return _download_metadata(
@@ -360,23 +387,28 @@ def get_meta(table_id, name, catalog_url=None):

def get_data(table_id, dir=None, typed=False, select=None, filters=None,
catalog_url=None):
"""
Get the CBS data table.
:param table_id: The indentifier of the table.
:param dir: Folder to save data to. If not given, data is not stored
"""Get the CBS data table.
Parameters
----------
table_id : str
The identifier of the table.
dir : str
Folder to save data to. If not given, data is not stored
on disk.
:param typed: Return a typed data table. Default False.
:param select: Column label or list of column labels to return.
:param filters: Return only rows that agree on the filter.
:type table_id: str
:type dir: str
:type typed: bool
:type select: list
:type filters: str
:returns: The requested data.
:rtype: list
typed : bool
Return a typed data table. Default False.
select : list
Column label or list of column labels to return.
filters : str
Return only rows that agree on the filter.
catalog_url : str
The url of the catalog. Default "opendata.cbs.nl".
Returns
-------
list
The requested data.
"""

_catalog_url = _get_catalog_url(catalog_url)
@@ -417,11 +449,13 @@ def get_data(table_id, dir=None, typed=False, select=None, filters=None,
def catalog(catalog_url, use_https=True):
"""Context manager for catalogs.
:param catalog_url: Base url for catalog. For example:
Parameters
----------
catalog_url : str
Url for the catalog. For example:
dataderden.cbs.nl.
:param use_https: Use https.
:type catalog_url: str
:type use_https: bool
use_https : bool
Use https. Default True.
"""

@@ -32,7 +32,8 @@
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc'
'sphinx.ext.autodoc',
'sphinx.ext.napoleon'
]

# Add any paths that contain templates here, relative to this directory.
@@ -340,3 +341,19 @@
# If true, do not generate a @detailmenu in the "Top" node's menu.
#
# texinfo_no_detailmenu = False


## Project settings

# Napoleon
napoleon_google_docstring = False
napoleon_numpy_docstring = True
napoleon_include_init_with_doc = False
napoleon_include_private_with_doc = False
napoleon_include_special_with_doc = True
napoleon_use_admonition_for_examples = False
napoleon_use_admonition_for_notes = False
napoleon_use_admonition_for_references = False
napoleon_use_ivar = False
napoleon_use_param = True
napoleon_use_rtype = True

0 comments on commit 3156e4c

Please sign in to comment.
You can’t perform that action at this time.