scripthelper 24.2__tar.gz → 26.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,293 +1,288 @@
1
- Metadata-Version: 2.3
1
+ Metadata-Version: 2.4
2
2
  Name: scripthelper
3
- Version: 24.2
3
+ Version: 26.1
4
4
  Summary: Helper module for creating simple Python scripts
5
- Project-URL: Homepage, https://github.com/presidento/scripthelper
6
- Project-URL: Changelog, https://github.com/presidento/scripthelper/blob/main/CHANGELOG.md
5
+ Author: Máté Farkas
7
6
  Author-email: Máté Farkas <fm@farkas-mate.hu>
8
- License: MIT License
9
- License-File: LICENSE
7
+ License-Expression: MIT
10
8
  Classifier: Development Status :: 5 - Production/Stable
11
9
  Classifier: Intended Audience :: Developers
12
10
  Classifier: Intended Audience :: System Administrators
13
- Classifier: License :: OSI Approved :: MIT License
14
11
  Classifier: Operating System :: OS Independent
15
- Classifier: Programming Language :: Python :: 3.9
16
- Classifier: Programming Language :: Python :: 3.10
17
12
  Classifier: Programming Language :: Python :: 3.11
18
13
  Classifier: Programming Language :: Python :: 3.12
19
14
  Classifier: Programming Language :: Python :: 3.13
15
+ Classifier: Programming Language :: Python :: 3.14
16
+ Classifier: Programming Language :: Python :: 3.15
20
17
  Classifier: Topic :: Utilities
21
18
  Classifier: Typing :: Typed
19
+ Requires-Dist: tqdm>=4.31.1
22
20
  Requires-Dist: coloredlogs>=10.0
23
- Requires-Dist: persistedstate>=23.6
24
- Requires-Dist: prettyprinter>=0.18.0
25
21
  Requires-Dist: stackprinter>=0.2.10
26
- Requires-Dist: tqdm>=4.31.1
27
- Provides-Extra: dev
28
- Requires-Dist: black; extra == 'dev'
29
- Requires-Dist: build; extra == 'dev'
30
- Requires-Dist: mypy; extra == 'dev'
31
- Requires-Dist: twine; extra == 'dev'
22
+ Requires-Dist: prettyprinter>=0.18.0
23
+ Requires-Dist: persistedstate>=23.6
24
+ Requires-Python: >=3.11
25
+ Project-URL: Homepage, https://github.com/presidento/scripthelper
26
+ Project-URL: Changelog, https://github.com/presidento/scripthelper/blob/main/CHANGELOG.md
32
27
  Description-Content-Type: text/markdown
33
28
 
34
- # scripthelper
35
-
36
- Helper module for simple command line Python scripts.
37
-
38
-
39
- ## Basic usage
40
-
41
- [example1.py](https://github.com/presidento/scripthelper/blob/master/example1.py):
42
-
43
- ```python
44
- #!/usr/bin/env python3
45
- import scripthelper
46
-
47
- logger = scripthelper.bootstrap()
48
-
49
- logger.critical("critical message")
50
- logger.error("error message")
51
- logger.warning("warning message")
52
- logger.info("info message")
53
- logger.verbose("verbose message")
54
- logger.debug("debug message")
55
- logger.spam("spam message")
56
- ```
57
-
58
- It just works. Try `--verbose` and `--quiet` command line options, too.
59
- It uses colored log messages on a terminal.
60
- See `--help` for more information.
61
-
62
- ## Adding other command line parameters
63
-
64
- [example2.py](https://github.com/presidento/scripthelper/blob/master/example2.py):
65
-
66
- ```python
67
- #!/usr/bin/env python3
68
- import scripthelper
69
-
70
- scripthelper.add_argument("-n", "--name", help="Name to greet")
71
- logger, args = scripthelper.bootstrap_args()
72
-
73
- if args.name:
74
- logger.debug("Name was provided")
75
- logger.info(f"Hello {args.name}")
76
- else:
77
- logger.warning("Name was not provided")
78
- ```
79
-
80
- For bigger scripts it is good idea to have the logger at the very beginning, and encapsulate the argument parsing phase, which is typically in the main function:
81
-
82
- [example2b.py](https://github.com/presidento/scripthelper/blob/master/example2b.py):
83
-
84
- ```python
85
- #!/usr/bin/env python3
86
- import scripthelper
87
-
88
- logger = scripthelper.getLogger()
89
-
90
-
91
- def greet(name):
92
- logger.info(f"Hello {name}")
93
-
94
-
95
- def main():
96
- scripthelper.add_argument("--name", default="World")
97
- args = scripthelper.initialize()
98
- greet(args.name)
99
-
100
-
101
- main()
102
- ```
103
-
104
- ## Progressbar works with logging, too
105
-
106
- [example3.py](https://github.com/presidento/scripthelper/blob/master/example3.py):
107
-
108
- ```python
109
- #!/usr/bin/env python3
110
- import scripthelper
111
- import time
112
-
113
- logger = scripthelper.bootstrap()
114
-
115
- logger.info("Doing the calculations...")
116
- for i in scripthelper.progressbar(range(100)):
117
- if i % 20 == 0:
118
- logger.verbose(f"Iteration {i}")
119
- if i % 5 == 0:
120
- logger.debug(f"Iteration {i}")
121
- if logger.isEnabledFor(scripthelper.SPAM):
122
- logger.spam(f"Iteration {i}")
123
- time.sleep(0.01)
124
- logger.info("Done")
125
- ```
126
-
127
- It is automatically disabled on non-tty `stderr` by default.
128
-
129
- ## Extended log levels can be used in modules
130
-
131
- [example4.py](https://github.com/presidento/scripthelper/blob/master/example4.py):
132
-
133
- ```python
134
- #!/usr/bin/env python3
135
- import scripthelper
136
- import example4module
137
-
138
- scripthelper.bootstrap()
139
- example4module.do_the_things()
140
- ```
141
-
142
- [example4module.py](https://github.com/presidento/scripthelper/blob/master/example4module.py):
143
-
144
- ```python
145
- #!/usr/bin/env python3
146
- import scripthelper
147
-
148
- logger = scripthelper.getLogger(__name__)
149
-
150
-
151
- def do_the_things():
152
- logger.verbose("Calling logger.verbose raises an exception if it does not work.")
153
- logger.info("Hello from a module.")
154
- ```
155
-
156
- ## You can easily preserve logs in files
157
-
158
- [example5.py](https://github.com/presidento/scripthelper/blob/master/example5.py):
159
-
160
- ```python
161
- #!/usr/bin/env python3
162
- import scripthelper
163
-
164
- logger = scripthelper.bootstrap()
165
- scripthelper.setup_file_logging()
166
-
167
- logger.critical("critical message")
168
- logger.error("error message")
169
- logger.warning("warning message")
170
- logger.info("info message")
171
- logger.verbose("verbose message")
172
- logger.debug("debug message")
173
- logger.spam("spam message")
174
- ```
175
-
176
- ## It handles exceptions, warnings
177
-
178
- [example6.py](https://github.com/presidento/scripthelper/blob/master/example6.py):
179
-
180
- ```python
181
- #!/usr/bin/env python3
182
- import scripthelper
183
-
184
- scripthelper.bootstrap()
185
-
186
- scripthelper.warn("This user warning will be captured.")
187
-
188
- this_variable = "will be displayed in stack trace"
189
- as_well_as = "the other variables"
190
- raise RuntimeError("This exception should be handled.")
191
- ```
192
-
193
- The local variables will be displayed in stack trace, for example:
194
-
195
- ```
196
- WARNING example6.py:6: UserWarning: This user warning will be captured.
197
- scripthelper.warn("This user warning will be captured.")
198
-
199
- CRITICAL Uncaught RuntimeError: This exception should be handled.
200
- File "example6.py", line 10, in <module>
201
- 6 scripthelper.warn("This user warning will be captured.")
202
- 7
203
- 8 this_variable = "will be displayed in stack trace"
204
- 9 as_well_as = "the other variables"
205
- --> 10 raise RuntimeError("This exception should be handled.")
206
- ..................................................
207
- this_variable = 'will be displayed in stack trace'
208
- as_well_as = 'the other variables'
209
- ..................................................
210
- ```
211
-
212
- ## Has built-in colored pretty printer
213
-
214
- [example7.py](https://github.com/presidento/scripthelper/blob/master/example7.py):
215
-
216
- ```python
217
- #!/usr/bin/env python3
218
- import scripthelper
219
- from dataclasses import dataclass
220
-
221
- scripthelper.bootstrap()
222
-
223
-
224
- @dataclass
225
- class Item:
226
- name: str
227
- value: int
228
-
229
-
230
- something = {
231
- "string": "value1",
232
- "bool": True,
233
- "none": None,
234
- "integer": 1234,
235
- "item": Item("name", 999),
236
- }
237
-
238
- scripthelper.pp(something)
239
- ```
240
-
241
- ## Has built-in persisted state handler
242
-
243
- The state is persisted immediately in the background in YAML. Mutable objects (`list`, `dict`) also can be used.
244
-
245
- [example9.py](https://github.com/presidento/scripthelper/blob/master/example9.py):
246
-
247
- ```python
248
- #!/usr/bin/env python3
249
- import scripthelper
250
-
251
- logger = scripthelper.bootstrap()
252
- state = scripthelper.PersistedState(processed_id=0, to_remember=[])
253
-
254
- state.processed_id += 1
255
- state.to_remember.append(f"Element {state.processed_id}")
256
- while len(state.to_remember) > 2:
257
- state.to_remember.pop(0)
258
-
259
- logger.info(f"Processing item #{state.processed_id}")
260
- for item in state.to_remember:
261
- logger.info(f"- {item}")
262
- ```
263
-
264
- ```
265
- $ python3 example9.py
266
- INFO example9 Processing item #1
267
- INFO example9 - Element 1
268
-
269
- $ python3 example9.py
270
- INFO example9 Processing item #2
271
- INFO example9 - Element 1
272
- INFO example9 - Element 2
273
-
274
- $ python3 example9.py
275
- INFO example9 Processing item #3
276
- INFO example9 - Element 2
277
- INFO example9 - Element 3
278
- ```
279
-
280
- ## Helps issuing a warning only once
281
-
282
- [example10.py](https://github.com/presidento/scripthelper/blob/master/example10.py):
283
-
284
- ```python
285
- #!/usr/bin/env python3
286
- import scripthelper
287
-
288
- scripthelper.bootstrap()
289
-
290
- for _ in range(10):
291
- scripthelper.warning_once("Item #12 has some errors")
292
- ```
293
-
29
+ # scripthelper
30
+
31
+ Helper module for simple command line Python scripts.
32
+
33
+
34
+ ## Basic usage
35
+
36
+ [example1.py](https://github.com/presidento/scripthelper/blob/master/example1.py):
37
+
38
+ ```python
39
+ #!/usr/bin/env python3
40
+ import scripthelper
41
+
42
+ logger = scripthelper.bootstrap()
43
+
44
+ logger.critical("critical message")
45
+ logger.error("error message")
46
+ logger.warning("warning message")
47
+ logger.info("info message")
48
+ logger.verbose("verbose message")
49
+ logger.debug("debug message")
50
+ logger.spam("spam message")
51
+ ```
52
+
53
+ It just works. Try `--verbose` and `--quiet` command line options, too.
54
+ It uses colored log messages on a terminal.
55
+ See `--help` for more information.
56
+
57
+ ## Adding other command line parameters
58
+
59
+ [example2.py](https://github.com/presidento/scripthelper/blob/master/example2.py):
60
+
61
+ ```python
62
+ #!/usr/bin/env python3
63
+ import scripthelper
64
+
65
+ scripthelper.add_argument("-n", "--name", help="Name to greet")
66
+ logger, args = scripthelper.bootstrap_args()
67
+
68
+ if args.name:
69
+ logger.debug("Name was provided")
70
+ logger.info(f"Hello {args.name}")
71
+ else:
72
+ logger.warning("Name was not provided")
73
+ ```
74
+
75
+ For bigger scripts it is good idea to have the logger at the very beginning, and encapsulate the argument parsing phase, which is typically in the main function:
76
+
77
+ [example2b.py](https://github.com/presidento/scripthelper/blob/master/example2b.py):
78
+
79
+ ```python
80
+ #!/usr/bin/env python3
81
+ import scripthelper
82
+
83
+ logger = scripthelper.getLogger()
84
+
85
+
86
+ def greet(name):
87
+ logger.info(f"Hello {name}")
88
+
89
+
90
+ def main():
91
+ scripthelper.add_argument("--name", default="World")
92
+ args = scripthelper.initialize()
93
+ greet(args.name)
94
+
95
+
96
+ main()
97
+ ```
98
+
99
+ ## Progressbar works with logging, too
100
+
101
+ [example3.py](https://github.com/presidento/scripthelper/blob/master/example3.py):
102
+
103
+ ```python
104
+ #!/usr/bin/env python3
105
+ import scripthelper
106
+ import time
107
+
108
+ logger = scripthelper.bootstrap()
109
+
110
+ logger.info("Doing the calculations...")
111
+ for i in scripthelper.progressbar(range(100)):
112
+ if i % 20 == 0:
113
+ logger.verbose(f"Iteration {i}")
114
+ if i % 5 == 0:
115
+ logger.debug(f"Iteration {i}")
116
+ if logger.isEnabledFor(scripthelper.SPAM):
117
+ logger.spam(f"Iteration {i}")
118
+ time.sleep(0.01)
119
+ logger.info("Done")
120
+ ```
121
+
122
+ It is automatically disabled on non-tty `stderr` by default.
123
+
124
+ ## Extended log levels can be used in modules
125
+
126
+ [example4.py](https://github.com/presidento/scripthelper/blob/master/example4.py):
127
+
128
+ ```python
129
+ #!/usr/bin/env python3
130
+ import scripthelper
131
+ import example4module
132
+
133
+ scripthelper.bootstrap()
134
+ example4module.do_the_things()
135
+ ```
136
+
137
+ [example4module.py](https://github.com/presidento/scripthelper/blob/master/example4module.py):
138
+
139
+ ```python
140
+ #!/usr/bin/env python3
141
+ import scripthelper
142
+
143
+ logger = scripthelper.getLogger(__name__)
144
+
145
+
146
+ def do_the_things():
147
+ logger.verbose("Calling logger.verbose raises an exception if it does not work.")
148
+ logger.info("Hello from a module.")
149
+ ```
150
+
151
+ ## You can easily preserve logs in files
152
+
153
+ [example5.py](https://github.com/presidento/scripthelper/blob/master/example5.py):
154
+
155
+ ```python
156
+ #!/usr/bin/env python3
157
+ import scripthelper
158
+
159
+ logger = scripthelper.bootstrap()
160
+ scripthelper.setup_file_logging()
161
+
162
+ logger.critical("critical message")
163
+ logger.error("error message")
164
+ logger.warning("warning message")
165
+ logger.info("info message")
166
+ logger.verbose("verbose message")
167
+ logger.debug("debug message")
168
+ logger.spam("spam message")
169
+ ```
170
+
171
+ ## It handles exceptions, warnings
172
+
173
+ [example6.py](https://github.com/presidento/scripthelper/blob/master/example6.py):
174
+
175
+ ```python
176
+ #!/usr/bin/env python3
177
+ import scripthelper
178
+
179
+ scripthelper.bootstrap()
180
+
181
+ scripthelper.warn("This user warning will be captured.")
182
+
183
+ this_variable = "will be displayed in stack trace"
184
+ as_well_as = "the other variables"
185
+ raise RuntimeError("This exception should be handled.")
186
+ ```
187
+
188
+ The local variables will be displayed in stack trace, for example:
189
+
190
+ ```
191
+ WARNING example6.py:6: UserWarning: This user warning will be captured.
192
+ scripthelper.warn("This user warning will be captured.")
193
+
194
+ CRITICAL Uncaught RuntimeError: This exception should be handled.
195
+ File "example6.py", line 10, in <module>
196
+ 6 scripthelper.warn("This user warning will be captured.")
197
+ 7
198
+ 8 this_variable = "will be displayed in stack trace"
199
+ 9 as_well_as = "the other variables"
200
+ --> 10 raise RuntimeError("This exception should be handled.")
201
+ ..................................................
202
+ this_variable = 'will be displayed in stack trace'
203
+ as_well_as = 'the other variables'
204
+ ..................................................
205
+ ```
206
+
207
+ ## Has built-in colored pretty printer
208
+
209
+ [example7.py](https://github.com/presidento/scripthelper/blob/master/example7.py):
210
+
211
+ ```python
212
+ #!/usr/bin/env python3
213
+ import scripthelper
214
+ from dataclasses import dataclass
215
+
216
+ scripthelper.bootstrap()
217
+
218
+
219
+ @dataclass
220
+ class Item:
221
+ name: str
222
+ value: int
223
+
224
+
225
+ something = {
226
+ "string": "value1",
227
+ "bool": True,
228
+ "none": None,
229
+ "integer": 1234,
230
+ "item": Item("name", 999),
231
+ }
232
+
233
+ scripthelper.pp(something)
234
+ ```
235
+
236
+ ## Has built-in persisted state handler
237
+
238
+ The state is persisted immediately in the background in YAML. Mutable objects (`list`, `dict`) also can be used.
239
+
240
+ [example9.py](https://github.com/presidento/scripthelper/blob/master/example9.py):
241
+
242
+ ```python
243
+ #!/usr/bin/env python3
244
+ import scripthelper
245
+
246
+ logger = scripthelper.bootstrap()
247
+ state = scripthelper.PersistedState(processed_id=0, to_remember=[])
248
+
249
+ state.processed_id += 1
250
+ state.to_remember.append(f"Element {state.processed_id}")
251
+ while len(state.to_remember) > 2:
252
+ state.to_remember.pop(0)
253
+
254
+ logger.info(f"Processing item #{state.processed_id}")
255
+ for item in state.to_remember:
256
+ logger.info(f"- {item}")
257
+ ```
258
+
259
+ ```
260
+ $ python3 example9.py
261
+ INFO example9 Processing item #1
262
+ INFO example9 - Element 1
263
+
264
+ $ python3 example9.py
265
+ INFO example9 Processing item #2
266
+ INFO example9 - Element 1
267
+ INFO example9 - Element 2
268
+
269
+ $ python3 example9.py
270
+ INFO example9 Processing item #3
271
+ INFO example9 - Element 2
272
+ INFO example9 - Element 3
273
+ ```
274
+
275
+ ## Helps issuing a warning only once
276
+
277
+ [example10.py](https://github.com/presidento/scripthelper/blob/master/example10.py):
278
+
279
+ ```python
280
+ #!/usr/bin/env python3
281
+ import scripthelper
282
+
283
+ scripthelper.bootstrap()
284
+
285
+ for _ in range(10):
286
+ scripthelper.warning_once("Item #12 has some errors")
287
+ ```
288
+
@@ -1,48 +1,63 @@
1
- [project]
2
- name = "scripthelper"
3
- version = "24.2"
4
- description = "Helper module for creating simple Python scripts"
5
- readme = "README.compiled.md"
6
- license = {text = "MIT License"}
7
- classifiers = [
8
- "Development Status :: 5 - Production/Stable",
9
- "Intended Audience :: Developers",
10
- "Intended Audience :: System Administrators",
11
- "License :: OSI Approved :: MIT License",
12
- "Operating System :: OS Independent",
13
- "Programming Language :: Python :: 3.9",
14
- "Programming Language :: Python :: 3.10",
15
- "Programming Language :: Python :: 3.11",
16
- "Programming Language :: Python :: 3.12",
17
- "Programming Language :: Python :: 3.13",
18
- "Topic :: Utilities",
19
- "Typing :: Typed",
20
- ]
21
- dependencies = [
22
- "tqdm >= 4.31.1",
23
- "coloredlogs >= 10.0",
24
- "stackprinter >= 0.2.10",
25
- "prettyprinter >= 0.18.0",
26
- "persistedstate >= 23.6",
27
- ]
28
-
29
- [project.optional-dependencies]
30
- dev = [
31
- "black",
32
- "build",
33
- "mypy",
34
- "twine",
35
- ]
36
-
37
-
38
- [[project.authors]]
39
- name = "Máté Farkas"
40
- email = "fm@farkas-mate.hu"
41
-
42
- [project.urls]
43
- Homepage = "https://github.com/presidento/scripthelper"
44
- Changelog = "https://github.com/presidento/scripthelper/blob/main/CHANGELOG.md"
45
-
46
- [build-system]
47
- requires = ["hatchling"]
48
- build-backend = "hatchling.build"
1
+ [project]
2
+ name = "scripthelper"
3
+ version = "26.1"
4
+ description = "Helper module for creating simple Python scripts"
5
+ readme = "README.compiled.md"
6
+ license = "MIT"
7
+ classifiers = [
8
+ "Development Status :: 5 - Production/Stable",
9
+ "Intended Audience :: Developers",
10
+ "Intended Audience :: System Administrators",
11
+ "Operating System :: OS Independent",
12
+ "Programming Language :: Python :: 3.11",
13
+ "Programming Language :: Python :: 3.12",
14
+ "Programming Language :: Python :: 3.13",
15
+ "Programming Language :: Python :: 3.14",
16
+ "Programming Language :: Python :: 3.15",
17
+ "Topic :: Utilities",
18
+ "Typing :: Typed",
19
+ ]
20
+ requires-python = ">=3.11"
21
+ dependencies = [
22
+ "tqdm >= 4.31.1",
23
+ "coloredlogs >= 10.0",
24
+ "stackprinter >= 0.2.10",
25
+ "prettyprinter >= 0.18.0",
26
+ "persistedstate >= 23.6",
27
+ ]
28
+
29
+ [[project.authors]]
30
+ name = "Máté Farkas"
31
+ email = "fm@farkas-mate.hu"
32
+
33
+ [project.urls]
34
+ Homepage = "https://github.com/presidento/scripthelper"
35
+ Changelog = "https://github.com/presidento/scripthelper/blob/main/CHANGELOG.md"
36
+
37
+ [dependency-groups]
38
+ dev = [
39
+ "black",
40
+ "mypy",
41
+ "tox-uv>=1.25",
42
+ "tox",
43
+ "uv",
44
+ ]
45
+
46
+ [tool.tox]
47
+ env_list = [
48
+ "py315",
49
+ "py314",
50
+ "py313",
51
+ "py312",
52
+ "py311",
53
+ ]
54
+
55
+ [tool.tox.env_run_base]
56
+ commands = [[
57
+ "python",
58
+ "test_examples.py",
59
+ ]]
60
+
61
+ [build-system]
62
+ requires = ["uv_build>=0.9.10,<0.14.0"]
63
+ build-backend = "uv_build"