Merge pull request #61 from PurplShip/document-purplship-sdk

update release version and draft README extended documentation

cli.py

@@ -0,0 +1,160 @@
+import click
+import inspect
+from jinja2 import Template
+from purplship.core.utils import to_dict
+
+MODELS_TEMPLATE = Template('''
+{% for name, cls in classes.items() %}
+- <a name="{{ name }}"></a> {{ name }}
+    | Name | Type | Description 
+    | --- | --- | --- |
+{% for prop, typedef in cls.__annotations__.items() %}    | `{{ prop }}` | {{ typedef }} | 
+{% endfor %}
+{% endfor %}
+''')
+
+SERVICES_TEMPLATE = Template('''
+{% for key, value in service_mappers.items() %}
+- <a name="services-{{ key }}"></a> {{ mappers[key]["label"] }}
+    Code | Identifier
+    --- | ---
+{% for code, name in value.items() %}    | `{{ code }}` | {{ name }}
+{% endfor %}
+{% endfor %}
+''')
+
+SHIPMENT_OPTIONS_TEMPLATE = Template('''
+{% for key, value in option_mappers.items() %}
+- <a name="options-{{ key }}"></a> {{ mappers[key]["label"] }}
+    Code | Identifier
+    --- | ---
+{% for code, name in value.items() %}    | `{{ code }}` | {{ name }}
+{% endfor %}
+{% endfor %}
+''')
+
+SHIPMENT_PRESETS_TEMPLATE = Template('''
+{% for key, value in preset_mappers.items() %}
+- <a name="presets-{{ key }}"></a> {{ mappers[key]["label"] }}
+    Code | Dimensions | Note
+    --- | --- | ---
+{% for code, dim in value.items() %}    {{ format_dimension(code, dim) }}
+{% endfor %}
+{% endfor %}
+''')
+
+
+def format_dimension(code, dim):
+    return f'| `{ code }` | { f" x ".join([str(d) for d in dim.values() if isinstance(d, float)]) } | { f" x ".join([k for k in dim.keys() if isinstance(dim[k], float)]) }'
+
+
+def import_pkg(pkg: str):
+    *_, carrier, name = pkg.split(".")
+    return __import__(pkg, fromlist=[name])
+
+
+PACKAGE_MAPPERS = {
+    'canadapost': {
+        'label': "Canada Post",
+        'package': import_pkg('purplship.carriers.canadapost.units'),
+        'services': "ServiceType",
+        'options': "OptionCode",
+        'packagePresets': "PackagePresets"
+    },
+    'dhl': {
+        'label': "DHL",
+        'package': import_pkg('purplship.carriers.dhl.units'),
+        'services': "Product",
+        'options': "SpecialServiceCode",
+        'packagePresets': "PackagePresets"
+    },
+    'fedex': {
+        'label': "FedEx",
+        'package': import_pkg('purplship.carriers.fedex.units'),
+        'services': "ServiceType",
+        'options': "SpecialServiceType",
+        'packagePresets': "PackagePresets"
+    },
+    'purolator': {
+        'label': "Purolator",
+        'package': import_pkg('purplship.carriers.purolator.units'),
+        'services': "Product",
+        'options': "Service",
+        'packagePresets': "PackagePresets"
+    },
+    'ups': {
+        'label': "UPS",
+        'package': import_pkg('purplship.carriers.ups.units'),
+        'services': "ShippingServiceCode",
+        'options': "ServiceOption",
+        'packagePresets': "PackagePresets"
+    }
+}
+
+
+@click.group()
+def cli():
+    pass
+
+
+@cli.command()
+def generate_shipment_options():
+    option_mappers = {
+        key: {c.name: c.value for c in list(getattr(mapper['package'], mapper['options']))}
+        for key, mapper in PACKAGE_MAPPERS.items()
+        if mapper.get('options') is not None
+    }
+    click.echo(SHIPMENT_OPTIONS_TEMPLATE.render(option_mappers=option_mappers, mappers=PACKAGE_MAPPERS))
+
+
+@cli.command()
+def generate_package_presets():
+    preset_mappers = {
+        key: {c.name: to_dict(c.value) for c in list(getattr(mapper['package'], mapper['packagePresets']))}
+        for key, mapper in PACKAGE_MAPPERS.items()
+        if mapper.get('packagePresets') is not None
+    }
+    click.echo(SHIPMENT_PRESETS_TEMPLATE.render(preset_mappers=preset_mappers, mappers=PACKAGE_MAPPERS, format_dimension=format_dimension))
+
+
+@cli.command()
+def generate_services():
+    service_mappers = {
+        key: {c.name: c.value for c in list(getattr(mapper['package'], mapper['services']))}
+        for key, mapper in PACKAGE_MAPPERS.items()
+        if mapper.get('services') is not None
+    }
+    click.echo(SERVICES_TEMPLATE.render(service_mappers=service_mappers, mappers=PACKAGE_MAPPERS))
+
+
+@cli.command()
+def generate_models():
+    import purplship.core.models as m
+    classes = {i: t for i, t in inspect.getmembers(m) if inspect.isclass(t)}
+    docstr = MODELS_TEMPLATE.render(
+        classes=classes
+    ).replace(
+        "purplship.core.models.", ""
+    ).replace(
+        "typing.", ""
+    ).replace(
+        "<class '", "`"
+    ).replace(
+        "'>", "`"
+    ).replace(
+        "Dict", "`dict`"
+    )
+
+    for name, _ in classes.items():
+        cls = name.strip()
+        docstr = docstr.replace(
+            f"| `{cls}` |", f"| [{cls}](#{cls}) |"
+        ).replace(
+            f"[{cls}] ", f"[[{cls}](#{cls})] "
+        )
+
+    click.echo(docstr)
+
+
+if __name__ == '__main__':
+    cli()

extensions/canadapost/setup.py

@@ -1,7 +1,7 @@
 from setuptools import setup, find_namespace_packages
 
 setup(name='purplship.canadapost',
-      version='2020.5.0',
+      version='2020.6.0',
       description='Multi-carrier shipping API integration with python',
       url='https://github.com/PurplShip/purplship',
       author='PurplShip',

extensions/dhl/setup.py

@@ -2,7 +2,7 @@
 
 
 setup(name='purplship.dhl',
-      version='2020.5.0',
+      version='2020.6.0',
       description='Multi-carrier shipping API integration with python',
       url='https://github.com/PurplShip/purplship',
       author='PurplShip',

extensions/fedex/setup.py

@@ -2,7 +2,7 @@
 
 
 setup(name='purplship.fedex',
-      version='2020.5.0',
+      version='2020.6.0',
       description='Multi-carrier shipping API integration with python',
       url='https://github.com/PurplShip/purplship',
       author='PurplShip',

extensions/freight/setup.py

@@ -2,7 +2,7 @@
 
 
 setup(name='purplship.freight',
-      version='2020.5.0',
+      version='2020.6.0',
       description='Multi-carrier shipping API integration with python',
       url='https://github.com/PurplShip/purplship',
       author='PurplShip',

extensions/package/setup.py

@@ -2,7 +2,7 @@
 
 
 setup(name='purplship.package',
-      version='2020.5.0',
+      version='2020.6.0',
       description='Multi-carrier shipping API integration with python',
       url='https://github.com/PurplShip/purplship',
       author='PurplShip',

extensions/purolator/setup.py

@@ -2,7 +2,7 @@
 
 
 setup(name='purplship.purolator',
-      version='2020.5.0',
+      version='2020.6.0',
       description='Multi-carrier shipping API integration with python',
       url='https://github.com/PurplShip/purplship',
       author='PurplShip',

extensions/ups/setup.py

@@ -2,7 +2,7 @@
 
 
 setup(name='purplship.ups',
-      version='2020.5.0',
+      version='2020.6.0',
       description='Multi-carrier shipping API integration with python',
       url='https://github.com/PurplShip/purplship',
       author='PurplShip',

extensions/usps/setup.py

@@ -2,7 +2,7 @@
 
 
 setup(name='purplship.usps',
-      version='2020.5.0',
+      version='2020.6.0',
       description='Multi-carrier shipping API integration with python',
       url='https://github.com/PurplShip/purplship',
       author='PurplShip',

purplship/core/models.py

@@ -234,7 +234,7 @@ class Message:
     carrier_name: str
     message: str = None
     code: str = None
-    details: dict = None
+    details: Dict = None
 
 
 @attr.s(auto_attribs=True)

script.sh

@@ -96,4 +96,8 @@ clean_builds() {
     find . -type d -not -path "*$ENV_DIR/*" -name "*.egg-info" -exec rm -r {} \; || true
 }
 
+cli() {
+  python "${ROOT:?}/cli.py" "$@"
+}
+
 env:on || true

setup.py

@@ -8,10 +8,12 @@
       "black",
       "coverage",
       "mypy",
+      "click",
+      "Jinja2"
 ]
 
 setup(name='purplship',
-      version='2020.5.0',
+      version='2020.6.0',
       description='Multi-carrier shipping API integration with python',
       long_description=long_description,
       long_description_content_type="text/markdown",