Skip to content

Commit a319705

Browse files
timothyhulltimothyhull
authored
Merge pull request #20 from timothyhull:timothyhull/docstring-refactor
docstring-refactor
2 parents 17b9cab + cf5f827 commit a319705

File tree

3 files changed

+146
-38
lines changed

3 files changed

+146
-38
lines changed

‎README.md

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,9 +18,13 @@
1818

1919
### Capabilities
2020

21-
- Converts Python iterable objects (`list`, `tuple`, `set`, etc.) into a `namedtuple` objects using a decorator function, **so you don't have to rewrite code that already returns iterable objects**.
21+
- Converts Python iterable objects (`list`, `tuple`, `set`, etc.) into `namedtuple` objects using a decorator function, **so you don't have to rewrite code that already returns iterable objects**.
2222

23-
- Gathers `namedtuple` attribute names via either a `kwarg` in a decorated function or using prompts to collect attribute names.
23+
- Sets `namedtuple` attribute names in one of three ways:
24+
25+
1. Entering attribute names at input prompts (default).
26+
2. Manually, by passing an iterable object of attribute names as a keyword argument to the decorated function.
27+
3. Setting a keyword argument to automatically generate attribute names.
2428

2529
- Automatically corrects attribute name entries that would be invalid.
2630

‎namedtuple_maker/namedtuple_logger.py

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
#!/usr/bin/env python3
2-
""" Perform logging functions for namedtuple_maker.py
2+
""" Perform logging functions for the namedtuple_maker.py module.
3+
4+
Imports the Logbook module (see 'Requirements' section below),
5+
initializes application logging to a file or STDOUT, and displays
6+
the configured log level in STDOUT.
37
48
Requirements:
59
Install Logbook with pip:
@@ -57,7 +61,16 @@ def initialize_logging(
5761
log_file: str = LOG_FILE,
5862
log_to_console: bool = False
5963
) -> None:
60-
""" Perform logging initialization functions.
64+
""" Perform logging initialization.
65+
66+
Starts application logging at a default level or, optionally,
67+
a specific level by keyword argument. Log entries write to an
68+
automatically-named time-rotating file series by default. A
69+
specific file name may be set manually by keyword argument.
70+
Optionally supports logging to STDOUT by keyword argument.
71+
72+
Raises an exception if the path to a manually set log file is
73+
not found.
6174
6275
Args:
6376
log_level (str, optional):

‎namedtuple_maker/namedtuple_maker.py

Lines changed: 125 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,129 @@
11
#!/usr/bin/env python3
2-
""" Convert an iterable object into a namedtuple using a decorator.
3-
Provide the namedtuple attribute names in a kwarg of the decorated
4-
function, or enter attribute names at prompts.
2+
""" Convert iterable objects into namedtuple objects using a decorator.
3+
4+
Converts Python iterable objects (list, tuple, set, etc.) into
5+
namedtuple objects using a decorator function, so you don't have to
6+
rewrite code that already returns iterable objects.
7+
8+
Installation:
9+
Install from PyPi - https://pypi.org/project/namedtuple-maker/
10+
pip install namedtuple-maker
511
612
Usage:
713
from namedtuple_maker.namedtuple_maker import named_tuple_converter
814
9-
@named_tuple_converter
10-
def your_function() -> Iterable:
11-
# your function code
12-
13-
Logging Level:
14-
The application creates a log level with a default
15-
logging level of 'INFO'. To set a different logging level,
16-
set an environment variable named LOG_LEVEL to one of the
17-
following case insensitive logging levels:
18-
19-
- FATAL
20-
- ERROR
21-
- CRITICAL
22-
- WARN
23-
- WARNING
24-
- INFO
25-
- NOTICE
26-
- DEBUG
27-
- TRACE
28-
29-
Example custom logging usage:
30-
export LOG_LEVEL=DEBUG
31-
32-
Logging Target:
33-
The application automatically creates a log file in the current
34-
working directory, and writes log message to that file. To
35-
write log messages to the console (STDOUT), set the
36-
LOG_TO_CONSOLE environment variable to 'True'.
37-
38-
Example logging target usage:
39-
export LOG_TO_CONSOLE=True
15+
Each index of the iterable object becomes a value in a new
16+
namedtuple object. The namedtuple attribute names may be set
17+
in one of three ways:
18+
19+
1. Entering attribute names at input prompts (default).
20+
21+
# Example iterable object
22+
my_object = [1, 2, 3]
23+
24+
# Decorate a function that returns an Iterable object
25+
@named_tuple_converter
26+
def my_function(
27+
iterable_input):
28+
29+
return iterable_input
30+
31+
# Call the decorated function
32+
my_namedtuple = my_function(
33+
iterable_input=my_object
34+
)
35+
# Follow prompts to assign attribute names
36+
Enter an attribute name for the value "1": a
37+
Enter an attribute name for the value "2": b
38+
Enter an attribute name for the value "3": c
39+
40+
# Review the namedtuple_object
41+
my_namedtuple
42+
NamedTuple(a=1, b=2, c=3)
43+
44+
2. Manually, by passing an iterable object of attribute
45+
names as a keyword argument to the decorated function.
46+
47+
# Example iterable object
48+
my_object = [1, 2, 3]
49+
50+
# Example attribute names
51+
my_attribute_names = ['a', 'b', 'c']
52+
53+
# Decorate a function that returns an Iterable object
54+
@named_tuple_converter
55+
def my_function(
56+
iterable_input,
57+
attribute_names):
58+
59+
return iterable_input
60+
61+
# Call the decorated function
62+
my_namedtuple = my_function(
63+
iterable_input=my_object,
64+
attribute_names=my_attribute_names
65+
)
66+
67+
# Review the namedtuple_object
68+
my_namedtuple
69+
NamedTuple(a=1, b=2, c=3)
70+
71+
3. Setting a keyword argument to automatically generate
72+
attribute names.
73+
74+
# Example iterable object
75+
my_object = [1, 2, 3]
76+
77+
# Decorate a function that returns an Iterable object
78+
@named_tuple_converter
79+
def my_function(
80+
iterable_input,
81+
auto_attribute_names):
82+
83+
return iterable_input
84+
85+
# Call the decorated function
86+
my_namedtuple = my_function(
87+
iterable_input=my_object,
88+
auto_attribute_names=True
89+
)
90+
91+
# Review the namedtuple_object
92+
my_namedtuple
93+
NamedTuple(index_0=1, index_1=2, index_2=3)
94+
95+
The program automatically corrects attribute name entries that
96+
would be invalid.
97+
98+
Logging:
99+
100+
Logging Level:
101+
The application creates a log level with a default
102+
logging level of 'INFO'. To set a different logging level,
103+
set an environment variable named LOG_LEVEL to one of the
104+
following case insensitive logging levels:
105+
106+
- FATAL
107+
- ERROR
108+
- CRITICAL
109+
- WARN
110+
- WARNING
111+
- INFO
112+
- NOTICE
113+
- DEBUG
114+
- TRACE
115+
116+
Example custom logging usage:
117+
export LOG_LEVEL=DEBUG
118+
119+
Logging Target:
120+
The application automatically creates a log file in the
121+
current working directory, and writes log message to that
122+
file. To write log messages to the console (STDOUT), set
123+
the LOG_TO_CONSOLE environment variable to 'True'.
124+
125+
Example logging target usage:
126+
export LOG_TO_CONSOLE=True
40127
"""
41128

42129
# Imports - Python Standard Library
@@ -140,6 +227,10 @@ def validate_attribute_input(
140227
) -> List:
141228
""" Validate or generate attribute names for a namedtuple.
142229
230+
Checks each attribute name for validity, automatically
231+
replacing invalid characters plus leading, trailing spaces, and
232+
mid-value spaces.
233+
143234
Args:
144235
attribute_names (List):
145236
Raw list of namedtuple attribute names from user input.

0 commit comments

Comments
 (0)