From fbeb05dd25c8b49a4433a5a5fd463a5660664d90 Mon Sep 17 00:00:00 2001 From: Tim Paine Date: Mon, 22 Apr 2019 16:45:52 -0400 Subject: [PATCH] adding more python docs --- docs/api.rst | 2 +- paperboy/config/base.py | 37 +++++++++++++++++++++++++++++++++++++ paperboy/config/forms.py | 5 +++++ paperboy/config/job.py | 10 ++++++++++ paperboy/config/notebook.py | 10 ++++++++++ paperboy/config/report.py | 10 ++++++++++ paperboy/config/user.py | 6 ++++++ paperboy/server/api.py | 8 ++++++++ 8 files changed, 87 insertions(+), 1 deletion(-) diff --git a/docs/api.rst b/docs/api.rst index 816fddb..cbd8643 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -4,13 +4,13 @@ API .. toctree:: :maxdepth: 4 - api/paperboy.server.rst api/paperboy.config.rst api/paperboy.scheduler.rst api/paperboy.scheduler.airflow.rst api/paperboy.storage.rst api/paperboy.storage.sqla.rst api/paperboy.storage.sqla.models.rst + api/paperboy.server.rst api/paperboy.output.rst api/paperboy.resources.rst diff --git a/paperboy/config/base.py b/paperboy/config/base.py index 7b78719..f4b847b 100644 --- a/paperboy/config/base.py +++ b/paperboy/config/base.py @@ -9,21 +9,58 @@ class Base(HasTraits): + '''Base HasTraits abstract base class for all paperboy configureables''' + def __init__(self, config, *args, **kwargs): super(Base, self).__init__(*args, **kwargs) self.config = config @staticmethod def from_json(jsn, config): + '''create a paperboy config object from a json + + Args: + jsn: python dictionary from json representing the configuration object + config: paperboy configuration to populate from json + + Returns: + subclass of Base populated from jsn + ''' raise NotImplementedError() def to_json(self, include_notebook=False): + '''convert a paperboy config to a json + + Args: + self: subclass of Base + include_notebook: if config would include a notebook (potentially several MB in size), should + we include it or strip it? + + Returns: + dict: python dictionary representing the response json + ''' raise NotImplementedError() def form(self): + '''generate a JSON form template for the subclass of Base + + Args: + self: subclass of Base + + Returns: + dict: python dictionary representing the form template as a JSON + ''' raise NotImplementedError() def edit(self): + '''generate a JSON edit template for the subclass of Base + + Args: + self: subclass of Base + + Returns: + dict: python dictionary representing the edit template as a JSON + ''' raise NotImplementedError() def entry(self): diff --git a/paperboy/config/forms.py b/paperboy/config/forms.py index 73d0c8a..ac5ae61 100644 --- a/paperboy/config/forms.py +++ b/paperboy/config/forms.py @@ -6,6 +6,7 @@ class FormEntry(HasTraits): + '''Form template entry to be rendered on the client''' name = Unicode(allow_none=False) type = Unicode(default_value='text') @@ -25,6 +26,7 @@ def _validate_type(self, proposal): hidden = Bool(default_value=False) def to_json(self): + '''Convert form entry to JSON''' ret = {} ret['name'] = self.name ret['type'] = self.type @@ -47,6 +49,7 @@ def to_json(self): class DOMEntry(HasTraits): + '''DOM node template to be rendered on the client''' name = Unicode(allow_none=False) type = Unicode(default_value='p') @@ -91,6 +94,7 @@ def from_json(jsn): class Response(HasTraits): + '''Response modal template for client''' entries = List() def to_json(self): @@ -101,6 +105,7 @@ def to_json(self): class ListResult(HasTraits): + '''List result metadata for pagination''' page = Int(default_value=1) pages = Int(default_value=1) count = Int(default_value=1) diff --git a/paperboy/config/job.py b/paperboy/config/job.py index 97ae8f4..44e3719 100644 --- a/paperboy/config/job.py +++ b/paperboy/config/job.py @@ -7,6 +7,7 @@ class JobMetadataConfig(HasTraits): + '''Paperboy configuration object representing a Job (metadata component)''' notebook = Instance(NotebookConfig) username = Unicode() userid = Unicode() @@ -26,6 +27,7 @@ def _validate_interval(self, proposal): modified = Instance(datetime) def to_json(self, include_notebook=False): + '''Convert JobMetadata to a JSON''' ret = {} ret['notebook'] = self.notebook.name if include_notebook: @@ -40,6 +42,7 @@ def to_json(self, include_notebook=False): @staticmethod def from_json(jsn): + '''Create JobMetadata from a JSON''' ret = JobMetadataConfig() for k, v in jsn.items(): if k in ('created', 'modified'): @@ -50,11 +53,13 @@ def from_json(jsn): class JobConfig(Base): + '''Paperboy configuration object representing a Job''' name = Unicode() id = Unicode() meta = Instance(JobMetadataConfig) def to_json(self, include_notebook=False): + '''Convert Job to a JSON''' ret = {} ret['name'] = self.name ret['id'] = self.id @@ -62,6 +67,7 @@ def to_json(self, include_notebook=False): return ret def form(self): + '''Generate Form template for client from a Job object''' f = Response() f.entries = [ FormEntry(name='name', type='text', label='Name', value=self.name, placeholder='Name for Job...', required=True), @@ -82,6 +88,7 @@ def form(self): @staticmethod def from_json(jsn, config): + '''Create Job from a JSON''' ret = JobConfig(config) ret.name = jsn['name'] ret.id = jsn['id'] @@ -90,6 +97,7 @@ def from_json(jsn, config): return ret def edit(self): + '''Generate Edit template for client from a Job object''' f = Response() f.entries = [ FormEntry(name='name', type='text', value=self.name, label='Name', placeholder='Name for Job...', required=True), @@ -106,6 +114,7 @@ def edit(self): return f.to_json() def entry(self): + '''Generate ListTable entry for client from a Job object''' f = Response() f.entries = [ DOMEntry(name='name', type='label', value=self.name, label='Name'), @@ -121,6 +130,7 @@ def entry(self): return f.to_json() def store(self): + '''Generate response modal for client when saving a Job object''' ret = Response() ret.entries = [ DOMEntry(type='h2', value='Success!'), diff --git a/paperboy/config/notebook.py b/paperboy/config/notebook.py index c615a3c..f340147 100644 --- a/paperboy/config/notebook.py +++ b/paperboy/config/notebook.py @@ -6,6 +6,7 @@ class NotebookMetadataConfig(HasTraits): + '''Paperboy configuration object representing a Notebook (metadata component)''' username = Unicode() userid = Unicode() @@ -22,6 +23,7 @@ class NotebookMetadataConfig(HasTraits): modified = Instance(datetime) def to_json(self, include_notebook=False): + '''Convert NotebookMetadata to a JSON''' ret = {} ret['username'] = self.username # ret['userid'] = self.userid @@ -37,6 +39,7 @@ def to_json(self, include_notebook=False): @staticmethod def from_json(jsn): + '''Create NotebookMetadata from a JSON''' ret = NotebookMetadataConfig() for k, v in jsn.items(): if k in ('created', 'modified'): @@ -47,11 +50,13 @@ def from_json(jsn): class NotebookConfig(Base): + '''Paperboy configuration object representing a Notebook''' name = Unicode() id = Unicode() meta = Instance(NotebookMetadataConfig) def to_json(self, include_notebook=False): + '''Convert Notebook to a JSON''' ret = {} ret['name'] = self.name ret['id'] = self.id @@ -59,6 +64,7 @@ def to_json(self, include_notebook=False): return ret def form(self): + '''Generate Form template for client from a Notebook object''' f = Response() f.entries = [ FormEntry(name='file', type='file', label='File', required=True), @@ -74,6 +80,7 @@ def form(self): @staticmethod def from_json(jsn, config): + '''Create Notebook from a JSON''' ret = NotebookConfig(config) ret.name = jsn.pop('name') ret.id = jsn.pop('id') @@ -86,6 +93,7 @@ def from_json(jsn, config): return ret def edit(self): + '''Generate Edit template for client from a Notebook object''' f = Response() f.entries = [ FormEntry(name='name', type='text', value=self.name, placeholder='Name for Job...', required=True), @@ -103,6 +111,7 @@ def edit(self): return f.to_json() def entry(self): + '''Generate ListTable entry for client from a Notebook object''' f = Response() f.entries = [ DOMEntry(name='name', type='label', value=self.name, label='Name'), @@ -121,6 +130,7 @@ def entry(self): return f.to_json() def store(self): + '''Generate response modal for client when saving a Notebook object''' ret = Response() ret.entries = [ DOMEntry(type='p', value='Success!'), diff --git a/paperboy/config/report.py b/paperboy/config/report.py index d58719f..83ea65a 100644 --- a/paperboy/config/report.py +++ b/paperboy/config/report.py @@ -29,6 +29,7 @@ def _type_to_template(output, strip_code): class ReportMetadataConfig(HasTraits): + '''Paperboy configuration object representing a Report (metadata component)''' notebook = Instance(NotebookConfig) job = Instance(JobConfig) @@ -48,6 +49,7 @@ class ReportMetadataConfig(HasTraits): modified = Instance(datetime) def to_json(self, include_notebook=False): + '''Convert ReportMetadata to a JSON''' ret = {} ret = {} ret['notebook'] = self.notebook.name @@ -76,6 +78,7 @@ def to_json(self, include_notebook=False): @staticmethod def from_json(jsn): + '''Create ReportMetadata from a JSON''' ret = ReportMetadataConfig() for k, v in jsn.items(): if k in ('created', 'modified', 'run'): @@ -86,11 +89,13 @@ def from_json(jsn): class ReportConfig(Base): + '''Paperboy configuration object representing a Report''' name = Unicode() id = Unicode() meta = Instance(ReportMetadataConfig) def to_json(self, include_notebook=False): + '''Convert Report to a JSON''' ret = {} ret['name'] = self.name ret['id'] = self.id @@ -98,6 +103,7 @@ def to_json(self, include_notebook=False): return ret def form(self): + '''Generate Form template for client from a Report object''' f = Response() f.entries = [ FormEntry(name='name', type='text', label='Name', placeholder='Name for Report...', required=True), @@ -114,6 +120,7 @@ def form(self): @staticmethod def from_json(jsn, config): + '''Create Report from a JSON''' ret = ReportConfig(config) ret.name = jsn['name'] ret.id = jsn['id'] @@ -123,6 +130,7 @@ def from_json(jsn, config): return ret def edit(self): + '''Generate Edit template for client from a Report object''' f = Response() f.entries = [ FormEntry(name='name', type='text', value=self.name, label='Name', placeholder='Name for Report...', required=True), @@ -141,6 +149,7 @@ def edit(self): return f.to_json() def entry(self): + '''Generate ListTable entry for client from a Report object''' f = Response() f.entries = [ DOMEntry(name='name', type='label', value=self.name, label='Name'), @@ -160,6 +169,7 @@ def entry(self): return f.to_json() def store(self): + '''Generate response modal for client when saving a Report object''' ret = Response() ret.entries = [ DOMEntry(type='h2', value='Success!'), diff --git a/paperboy/config/user.py b/paperboy/config/user.py index 48ef1e6..2c38eee 100644 --- a/paperboy/config/user.py +++ b/paperboy/config/user.py @@ -5,16 +5,19 @@ class UserConfig(Base): + '''Paperboy configuration object representing a User''' name = Unicode() id = Unicode() def to_json(self): + '''Convert User to a JSON''' ret = {} ret['name'] = self.name ret['id'] = self.id return ret def form(self): + '''Generate Form template for client from a User object''' f = Response() f.entries = [ FormEntry(name='name', type='text', label='Name', placeholder='Name for Notebook...', required=True), @@ -24,12 +27,14 @@ def form(self): @staticmethod def from_json(jsn, config): + '''Create User from a JSON''' ret = UserConfig(config) ret.name = jsn.pop('name') ret.id = jsn.pop('id') return ret def edit(self): + '''Generate Edit template for client from a User object''' f = Response() f.entries = [ FormEntry(name='name', type='text', value=self.name, placeholder='Name for Job...', required=True), @@ -38,6 +43,7 @@ def edit(self): return f.to_json() def store(self): + '''Generate response modal for client when saving a User object''' ret = Response() ret.entries = [ DOMEntry(type='p', value='Success!'), diff --git a/paperboy/server/api.py b/paperboy/server/api.py index 645a4c4..5629b29 100644 --- a/paperboy/server/api.py +++ b/paperboy/server/api.py @@ -8,6 +8,14 @@ def FalconAPI(config): + '''Create falcon.API application from Paperboy traitlets application + + Args: + config (paperboy.config.application.Paperboy): traitlets configuration for application + + Returns: + falcon.API: the routed falcon api to launch with gunicorn/waitress + ''' def from_base(url): return urljoin(config.baseurl, url)