Skip to content

Commit fbeb05d

Browse files
timkpainetimkpaine
committed
adding more python docs
1 parent f3452cb commit fbeb05d

File tree

8 files changed

+87
-1
lines changed

8 files changed

+87
-1
lines changed

‎docs/api.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,13 @@ API
44
.. toctree::
55
:maxdepth: 4
66

7-
api/paperboy.server.rst
87
api/paperboy.config.rst
98
api/paperboy.scheduler.rst
109
api/paperboy.scheduler.airflow.rst
1110
api/paperboy.storage.rst
1211
api/paperboy.storage.sqla.rst
1312
api/paperboy.storage.sqla.models.rst
13+
api/paperboy.server.rst
1414
api/paperboy.output.rst
1515
api/paperboy.resources.rst
1616

‎paperboy/config/base.py

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,21 +9,58 @@
99

1010

1111
class Base(HasTraits):
12+
'''Base HasTraits abstract base class for all paperboy configureables'''
13+
1214
def __init__(self, config, *args, **kwargs):
1315
super(Base, self).__init__(*args, **kwargs)
1416
self.config = config
1517

1618
@staticmethod
1719
def from_json(jsn, config):
20+
'''create a paperboy config object from a json
21+
22+
Args:
23+
jsn: python dictionary from json representing the configuration object
24+
config: paperboy configuration to populate from json
25+
26+
Returns:
27+
subclass of Base populated from jsn
28+
'''
1829
raise NotImplementedError()
1930

2031
def to_json(self, include_notebook=False):
32+
'''convert a paperboy config to a json
33+
34+
Args:
35+
self: subclass of Base
36+
include_notebook: if config would include a notebook (potentially several MB in size), should
37+
we include it or strip it?
38+
39+
Returns:
40+
dict: python dictionary representing the response json
41+
'''
2142
raise NotImplementedError()
2243

2344
def form(self):
45+
'''generate a JSON form template for the subclass of Base
46+
47+
Args:
48+
self: subclass of Base
49+
50+
Returns:
51+
dict: python dictionary representing the form template as a JSON
52+
'''
2453
raise NotImplementedError()
2554

2655
def edit(self):
56+
'''generate a JSON edit template for the subclass of Base
57+
58+
Args:
59+
self: subclass of Base
60+
61+
Returns:
62+
dict: python dictionary representing the edit template as a JSON
63+
'''
2764
raise NotImplementedError()
2865

2966
def entry(self):

‎paperboy/config/forms.py

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66

77

88
class FormEntry(HasTraits):
9+
'''Form template entry to be rendered on the client'''
910
name = Unicode(allow_none=False)
1011
type = Unicode(default_value='text')
1112

@@ -25,6 +26,7 @@ def _validate_type(self, proposal):
2526
hidden = Bool(default_value=False)
2627

2728
def to_json(self):
29+
'''Convert form entry to JSON'''
2830
ret = {}
2931
ret['name'] = self.name
3032
ret['type'] = self.type
@@ -47,6 +49,7 @@ def to_json(self):
4749

4850

4951
class DOMEntry(HasTraits):
52+
'''DOM node template to be rendered on the client'''
5053
name = Unicode(allow_none=False)
5154
type = Unicode(default_value='p')
5255

@@ -91,6 +94,7 @@ def from_json(jsn):
9194

9295

9396
class Response(HasTraits):
97+
'''Response modal template for client'''
9498
entries = List()
9599

96100
def to_json(self):
@@ -101,6 +105,7 @@ def to_json(self):
101105

102106

103107
class ListResult(HasTraits):
108+
'''List result metadata for pagination'''
104109
page = Int(default_value=1)
105110
pages = Int(default_value=1)
106111
count = Int(default_value=1)

‎paperboy/config/job.py

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77

88

99
class JobMetadataConfig(HasTraits):
10+
'''Paperboy configuration object representing a Job (metadata component)'''
1011
notebook = Instance(NotebookConfig)
1112
username = Unicode()
1213
userid = Unicode()
@@ -26,6 +27,7 @@ def _validate_interval(self, proposal):
2627
modified = Instance(datetime)
2728

2829
def to_json(self, include_notebook=False):
30+
'''Convert JobMetadata to a JSON'''
2931
ret = {}
3032
ret['notebook'] = self.notebook.name
3133
if include_notebook:
@@ -40,6 +42,7 @@ def to_json(self, include_notebook=False):
4042

4143
@staticmethod
4244
def from_json(jsn):
45+
'''Create JobMetadata from a JSON'''
4346
ret = JobMetadataConfig()
4447
for k, v in jsn.items():
4548
if k in ('created', 'modified'):
@@ -50,18 +53,21 @@ def from_json(jsn):
5053

5154

5255
class JobConfig(Base):
56+
'''Paperboy configuration object representing a Job'''
5357
name = Unicode()
5458
id = Unicode()
5559
meta = Instance(JobMetadataConfig)
5660

5761
def to_json(self, include_notebook=False):
62+
'''Convert Job to a JSON'''
5863
ret = {}
5964
ret['name'] = self.name
6065
ret['id'] = self.id
6166
ret['meta'] = self.meta.to_json(include_notebook)
6267
return ret
6368

6469
def form(self):
70+
'''Generate Form template for client from a Job object'''
6571
f = Response()
6672
f.entries = [
6773
FormEntry(name='name', type='text', label='Name', value=self.name, placeholder='Name for Job...', required=True),
@@ -82,6 +88,7 @@ def form(self):
8288

8389
@staticmethod
8490
def from_json(jsn, config):
91+
'''Create Job from a JSON'''
8592
ret = JobConfig(config)
8693
ret.name = jsn['name']
8794
ret.id = jsn['id']
@@ -90,6 +97,7 @@ def from_json(jsn, config):
9097
return ret
9198

9299
def edit(self):
100+
'''Generate Edit template for client from a Job object'''
93101
f = Response()
94102
f.entries = [
95103
FormEntry(name='name', type='text', value=self.name, label='Name', placeholder='Name for Job...', required=True),
@@ -106,6 +114,7 @@ def edit(self):
106114
return f.to_json()
107115

108116
def entry(self):
117+
'''Generate ListTable entry for client from a Job object'''
109118
f = Response()
110119
f.entries = [
111120
DOMEntry(name='name', type='label', value=self.name, label='Name'),
@@ -121,6 +130,7 @@ def entry(self):
121130
return f.to_json()
122131

123132
def store(self):
133+
'''Generate response modal for client when saving a Job object'''
124134
ret = Response()
125135
ret.entries = [
126136
DOMEntry(type='h2', value='Success!'),

‎paperboy/config/notebook.py

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66

77

88
class NotebookMetadataConfig(HasTraits):
9+
'''Paperboy configuration object representing a Notebook (metadata component)'''
910
username = Unicode()
1011
userid = Unicode()
1112

@@ -22,6 +23,7 @@ class NotebookMetadataConfig(HasTraits):
2223
modified = Instance(datetime)
2324

2425
def to_json(self, include_notebook=False):
26+
'''Convert NotebookMetadata to a JSON'''
2527
ret = {}
2628
ret['username'] = self.username
2729
# ret['userid'] = self.userid
@@ -37,6 +39,7 @@ def to_json(self, include_notebook=False):
3739

3840
@staticmethod
3941
def from_json(jsn):
42+
'''Create NotebookMetadata from a JSON'''
4043
ret = NotebookMetadataConfig()
4144
for k, v in jsn.items():
4245
if k in ('created', 'modified'):
@@ -47,18 +50,21 @@ def from_json(jsn):
4750

4851

4952
class NotebookConfig(Base):
53+
'''Paperboy configuration object representing a Notebook'''
5054
name = Unicode()
5155
id = Unicode()
5256
meta = Instance(NotebookMetadataConfig)
5357

5458
def to_json(self, include_notebook=False):
59+
'''Convert Notebook to a JSON'''
5560
ret = {}
5661
ret['name'] = self.name
5762
ret['id'] = self.id
5863
ret['meta'] = self.meta.to_json(include_notebook)
5964
return ret
6065

6166
def form(self):
67+
'''Generate Form template for client from a Notebook object'''
6268
f = Response()
6369
f.entries = [
6470
FormEntry(name='file', type='file', label='File', required=True),
@@ -74,6 +80,7 @@ def form(self):
7480

7581
@staticmethod
7682
def from_json(jsn, config):
83+
'''Create Notebook from a JSON'''
7784
ret = NotebookConfig(config)
7885
ret.name = jsn.pop('name')
7986
ret.id = jsn.pop('id')
@@ -86,6 +93,7 @@ def from_json(jsn, config):
8693
return ret
8794

8895
def edit(self):
96+
'''Generate Edit template for client from a Notebook object'''
8997
f = Response()
9098
f.entries = [
9199
FormEntry(name='name', type='text', value=self.name, placeholder='Name for Job...', required=True),
@@ -103,6 +111,7 @@ def edit(self):
103111
return f.to_json()
104112

105113
def entry(self):
114+
'''Generate ListTable entry for client from a Notebook object'''
106115
f = Response()
107116
f.entries = [
108117
DOMEntry(name='name', type='label', value=self.name, label='Name'),
@@ -121,6 +130,7 @@ def entry(self):
121130
return f.to_json()
122131

123132
def store(self):
133+
'''Generate response modal for client when saving a Notebook object'''
124134
ret = Response()
125135
ret.entries = [
126136
DOMEntry(type='p', value='Success!'),

‎paperboy/config/report.py

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ def _type_to_template(output, strip_code):
2929

3030

3131
class ReportMetadataConfig(HasTraits):
32+
'''Paperboy configuration object representing a Report (metadata component)'''
3233
notebook = Instance(NotebookConfig)
3334
job = Instance(JobConfig)
3435

@@ -48,6 +49,7 @@ class ReportMetadataConfig(HasTraits):
4849
modified = Instance(datetime)
4950

5051
def to_json(self, include_notebook=False):
52+
'''Convert ReportMetadata to a JSON'''
5153
ret = {}
5254
ret = {}
5355
ret['notebook'] = self.notebook.name
@@ -76,6 +78,7 @@ def to_json(self, include_notebook=False):
7678

7779
@staticmethod
7880
def from_json(jsn):
81+
'''Create ReportMetadata from a JSON'''
7982
ret = ReportMetadataConfig()
8083
for k, v in jsn.items():
8184
if k in ('created', 'modified', 'run'):
@@ -86,18 +89,21 @@ def from_json(jsn):
8689

8790

8891
class ReportConfig(Base):
92+
'''Paperboy configuration object representing a Report'''
8993
name = Unicode()
9094
id = Unicode()
9195
meta = Instance(ReportMetadataConfig)
9296

9397
def to_json(self, include_notebook=False):
98+
'''Convert Report to a JSON'''
9499
ret = {}
95100
ret['name'] = self.name
96101
ret['id'] = self.id
97102
ret['meta'] = self.meta.to_json(include_notebook)
98103
return ret
99104

100105
def form(self):
106+
'''Generate Form template for client from a Report object'''
101107
f = Response()
102108
f.entries = [
103109
FormEntry(name='name', type='text', label='Name', placeholder='Name for Report...', required=True),
@@ -114,6 +120,7 @@ def form(self):
114120

115121
@staticmethod
116122
def from_json(jsn, config):
123+
'''Create Report from a JSON'''
117124
ret = ReportConfig(config)
118125
ret.name = jsn['name']
119126
ret.id = jsn['id']
@@ -123,6 +130,7 @@ def from_json(jsn, config):
123130
return ret
124131

125132
def edit(self):
133+
'''Generate Edit template for client from a Report object'''
126134
f = Response()
127135
f.entries = [
128136
FormEntry(name='name', type='text', value=self.name, label='Name', placeholder='Name for Report...', required=True),
@@ -141,6 +149,7 @@ def edit(self):
141149
return f.to_json()
142150

143151
def entry(self):
152+
'''Generate ListTable entry for client from a Report object'''
144153
f = Response()
145154
f.entries = [
146155
DOMEntry(name='name', type='label', value=self.name, label='Name'),
@@ -160,6 +169,7 @@ def entry(self):
160169
return f.to_json()
161170

162171
def store(self):
172+
'''Generate response modal for client when saving a Report object'''
163173
ret = Response()
164174
ret.entries = [
165175
DOMEntry(type='h2', value='Success!'),

‎paperboy/config/user.py

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,19 @@
55

66

77
class UserConfig(Base):
8+
'''Paperboy configuration object representing a User'''
89
name = Unicode()
910
id = Unicode()
1011

1112
def to_json(self):
13+
'''Convert User to a JSON'''
1214
ret = {}
1315
ret['name'] = self.name
1416
ret['id'] = self.id
1517
return ret
1618

1719
def form(self):
20+
'''Generate Form template for client from a User object'''
1821
f = Response()
1922
f.entries = [
2023
FormEntry(name='name', type='text', label='Name', placeholder='Name for Notebook...', required=True),
@@ -24,12 +27,14 @@ def form(self):
2427

2528
@staticmethod
2629
def from_json(jsn, config):
30+
'''Create User from a JSON'''
2731
ret = UserConfig(config)
2832
ret.name = jsn.pop('name')
2933
ret.id = jsn.pop('id')
3034
return ret
3135

3236
def edit(self):
37+
'''Generate Edit template for client from a User object'''
3338
f = Response()
3439
f.entries = [
3540
FormEntry(name='name', type='text', value=self.name, placeholder='Name for Job...', required=True),
@@ -38,6 +43,7 @@ def edit(self):
3843
return f.to_json()
3944

4045
def store(self):
46+
'''Generate response modal for client when saving a User object'''
4147
ret = Response()
4248
ret.entries = [
4349
DOMEntry(type='p', value='Success!'),

0 commit comments

Comments
 (0)