Page Comparison

Page Contents

...

1. The library hides CKAN's idiosyncrasies and tries to make the library match the HDX user interface experience. The user does not need to learn about CKAN and the library makes it easier to understand what will be the result in HDX when calling a Python method.
   
   
2. The class structure of the library should be as logical as possible (within the restrictions of the CKAN API it relies on). In HDX, a dataset can contain zero or more resources and a gallery (consisting of gallery itemsit can be in one or more showcases (which themselves can contain more than one dataset), so the library reflects this even though the CKAN API presents a different interface for gallery items to resourcesshowcase API comes from a plugin and is not part of the core CKAN API. 

   The UML diagram below shows the relationships between the major classes in the library.  

   Include Page
   UML Diagram UML Diagram

3. Datasets, resources and gallery items showcases can use dictionary methods like square brackets to handle metadata which feels natural. (The HDXObject class extends UserDict.) eg.

   dataset['name'] = 'My Dataset'

   
   

4. Static metadata can be imported from a YAML file, recommended for being very human readable, or a JSON file eg.

   dataset.update_yaml([path])

   Static metadata can be passed in as a dictionary on initialisation of a dataset, resource or gallery item showcase eg.

   dataset = Dataset(configuration, {
       'name': slugified_name,
       'title': title,
   })

   
   

5. There are functions to help with adding more complicated types like dates and date ranges,

   
   '

   locations etc. eg.

   dataset.set_dataset_date(': dataset_dateSTART DATE', # has to be MM/DD/YYYY
       'groups': iso
   }'END DATE', 'FORMAT')

   
   

6. There are separate country code and utility libraries that provide functions to handle converting between country codes, dictionary merging, loading multiple YAML or JSON files and a few other helpful tasks eg. 

   def script_dir_plus_file(filename: str, pyobject: Any, follow_symlinks: Optional[bool] = True) -> str:
       """Get current script's directory and then append a filename

       Args:
           filename (str): Filename to append to directory path
           pyobject (Any): Any Python object in the script
           follow_symlinks (Optional[bool]): Follow symlinks or not. Defaults to True.

       Returns:
           str: Current script's directory and with filename appended
    """Country.get_iso3_country_code_fuzzy('Czech Rep.')

Easy Configuration and Logging

...

1. The code is very well documented. Detailed API documentation (generated from Google style docstrings using Sphinx) is available and mentioned in the Getting Started guide. 

   def load_from_hdx(self, id_or_name: str) -> bool:
       """Loads the dataset given by either id or name from HDX

       Args:
           id_or_name (str): Either id or name of dataset

       Returns:
           bool: True if loaded, False if not

   """

   

   IDEs can take advantage of the documentation eg.
   
   
   

2. The method arguments and return parameter have type hints. (Although this is a feature of Python 3.5, it has been backported.) Type hints enable sophisticated IDEs like PyCharm to warn of any inconsistencies in using types bringing one of the major benefits of statically typed languages to Python.
   

   def merge_dictionaries(dicts: List[dict]) -> dict:

   gives: 
   
   
   

3. Default parameters mean that there is a very easy default way to get set up and going eg.
   

   def update_yaml(self, path: Optional[str] = join('config', 'hdx_dataset_static.yml')) -> None:

...