itw-python-builder 0.2.15__tar.gz → 0.2.16__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.
Files changed (28) hide show
  1. {itw_python_builder-0.2.15 → itw_python_builder-0.2.16}/PKG-INFO +36 -22
  2. {itw_python_builder-0.2.15 → itw_python_builder-0.2.16}/README.md +35 -21
  3. itw_python_builder-0.2.16/itw_python_builder/cli.py +63 -0
  4. {itw_python_builder-0.2.15 → itw_python_builder-0.2.16}/itw_python_builder/task_utils.py +22 -13
  5. {itw_python_builder-0.2.15 → itw_python_builder-0.2.16}/itw_python_builder/tasks.py +261 -57
  6. itw_python_builder-0.2.16/itw_python_builder/templates/task_template.md +11 -0
  7. itw_python_builder-0.2.16/itw_python_builder/timesheet.py +134 -0
  8. {itw_python_builder-0.2.15 → itw_python_builder-0.2.16}/itw_python_builder.egg-info/PKG-INFO +36 -22
  9. {itw_python_builder-0.2.15 → itw_python_builder-0.2.16}/itw_python_builder.egg-info/SOURCES.txt +1 -0
  10. {itw_python_builder-0.2.15 → itw_python_builder-0.2.16}/pyproject.toml +1 -1
  11. itw_python_builder-0.2.15/itw_python_builder/cli.py +0 -35
  12. itw_python_builder-0.2.15/itw_python_builder/templates/task_template.md +0 -28
  13. {itw_python_builder-0.2.15 → itw_python_builder-0.2.16}/LICENSE +0 -0
  14. {itw_python_builder-0.2.15 → itw_python_builder-0.2.16}/itw_python_builder/.pylintrc +0 -0
  15. {itw_python_builder-0.2.15 → itw_python_builder-0.2.16}/itw_python_builder/__init__.py +0 -0
  16. {itw_python_builder-0.2.15 → itw_python_builder-0.2.16}/itw_python_builder/_pyruntime/sitecustomize.py +0 -0
  17. {itw_python_builder-0.2.15 → itw_python_builder-0.2.16}/itw_python_builder/notify.py +0 -0
  18. {itw_python_builder-0.2.15 → itw_python_builder-0.2.16}/itw_python_builder/ssr_tasks.py +0 -0
  19. {itw_python_builder-0.2.15 → itw_python_builder-0.2.16}/itw_python_builder/templates/new_version_email.html +0 -0
  20. {itw_python_builder-0.2.15 → itw_python_builder-0.2.16}/itw_python_builder/templates/server.sitemap.snippet.ts +0 -0
  21. {itw_python_builder-0.2.15 → itw_python_builder-0.2.16}/itw_python_builder/templates/sitemap.routes.ts +0 -0
  22. {itw_python_builder-0.2.15 → itw_python_builder-0.2.16}/itw_python_builder/utils.py +0 -0
  23. {itw_python_builder-0.2.15 → itw_python_builder-0.2.16}/itw_python_builder/version.py +0 -0
  24. {itw_python_builder-0.2.15 → itw_python_builder-0.2.16}/itw_python_builder.egg-info/dependency_links.txt +0 -0
  25. {itw_python_builder-0.2.15 → itw_python_builder-0.2.16}/itw_python_builder.egg-info/entry_points.txt +0 -0
  26. {itw_python_builder-0.2.15 → itw_python_builder-0.2.16}/itw_python_builder.egg-info/requires.txt +0 -0
  27. {itw_python_builder-0.2.15 → itw_python_builder-0.2.16}/itw_python_builder.egg-info/top_level.txt +0 -0
  28. {itw_python_builder-0.2.15 → itw_python_builder-0.2.16}/setup.cfg +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: itw_python_builder
3
- Version: 0.2.15
3
+ Version: 0.2.16
4
4
  Summary: Standardized Django deployment pipeline with Docker, testing, and SonarQube integration
5
5
  Author-email: IT-Works <contact@it-works.io>
6
6
  License: MIT
@@ -101,6 +101,35 @@ itw incrementpatch
101
101
  - `itw incrementrc` — Increment release candidate (staging)
102
102
  - `itw release` — Promote RC to stable release (master)
103
103
 
104
+ ### Timesheet Reporting for Frontend Releases
105
+
106
+ Pass `-tm` to any deployment command to report a merge request to Timesheet before publishing:
107
+
108
+ ```bash
109
+ # Find a specific MR number merged today in the current GitLab group
110
+ itw incrementpatch -tm 110
111
+
112
+ # Choose from today's merged MRs in the terminal
113
+ itw incrementrc -tm
114
+ ```
115
+
116
+ `--tm` and `--tm=110` are also supported. The option is available on `incrementrc`, `incrementpatch`, `incrementminor`, `incrementmajor` and `release`, for frontend projects on their allowed `staging`/`master` branches. Backend projects reject it before authentication or release work.
117
+
118
+ The current group is the full namespace of the origin repository; the search includes its subgroups and all accessible projects, including backend repositories. It uses the existing GitLab login and matches `merged_at` against today's calendar day in the local timezone. The number is the project-local MR number shown in GitLab, such as `!110`. If that number matches several repositories, you must choose one. Without a number, you must choose from the listed MRs even when only one is available. An interactive selection requires a terminal; a unique explicit number works without one. No matching MR stops the release with a message naming the number and group.
119
+
120
+ Configure Timesheet in the builder's root `.env`:
121
+
122
+ ```dotenv
123
+ TIMESHEET_REPORT_URL=https://tm.it-works.io/api/qa-issue-from-merge-request/
124
+ QA_ISSUE_API_KEY=<shared-api-key>
125
+ ```
126
+
127
+ Both values are required and are read only from the `.env` in the builder's root, resolved relative to the package location. The project being released and environment variables do not override this configuration.
128
+
129
+ After the tests and analysis pass, `itw` sends one POST to `TIMESHEET_REPORT_URL`, before creating a tag or changing/publishing the version. The request headers are `X-Api-Key` (the configured API key), `Version` (for example `1.2.3`, without the tag prefix or RC suffix), `Merge-Request-Repo` (the selected MR's `group/project`) and `Merge-Request-Id` (its MR number).
130
+
131
+ An HTTP error stops the release and displays the response's `message` (or `MESSAGE`); non-JSON error responses and connection/timeout failures also stop it with their error details. Reporting is not automatically retried. `--skip-pipeline` still reports to Timesheet, and SSR or multiple production environments report once per release. If a later build or upload fails, the existing Timesheet report is not rolled back. Commands without `-tm` do not search MRs or report to Timesheet.
132
+
104
133
  ### Authentication Commands
105
134
 
106
135
  - `itw login` — Capture and cache a GitLab token (backend also logs into the container registry)
@@ -150,6 +179,8 @@ itw test --target=core.service
150
179
 
151
180
  ### SSR Builds
152
181
 
182
+ On a production frontend deploy (`master`), `itw` looks in `src/environments` for `*.prod.ts` files. One file keeps the existing `build-master` script and uploads `frontend/<version>/dist.tar.gz`. Several files prompt for which one to deploy, with `all` as the last choice. Each selected environment is built with the matching `angular.json` configuration, packaged as `dist-<environment>.tar.gz`, and uploaded before the next one starts, at `frontend/<version>/dist-<environment>.tar.gz`. The version commit then includes that name, for example `version update to v.1.2.3-release (lenslight)`. Choosing `all` lists every name: `version update to v.1.2.3-release (greenterrace, lenslight)`.
183
+
153
184
  Frontend projects scaffolded with `itw ssr-init` build through the SSR npm scripts when `--ssr` is passed:
154
185
  ```bash
155
186
  itw incrementrc --ssr
@@ -219,42 +250,25 @@ Then fill it in and run:
219
250
  itw task --file=TASK.md
220
251
  ```
221
252
 
222
- `task-init` refuses to overwrite an existing `TASK.md`.
253
+ `task-init` refuses to overwrite an existing `TASK.md`. Without `.git` in the current directory, repo and milestone stay empty. With `.git`, it reads the GitLab remote and finds the namespace's `_pm` repositories. A single repository is selected automatically; several prompt for a selection. Milestones from the selected project and its parent groups follow the same selection rule, and the chosen milestone's available start/end dates are filled in. When no milestones exist, the milestone stays empty and the date placeholders are kept.
223
254
 
224
255
  ### Template
225
256
 
226
257
  ```markdown
227
- <!-- OPTIONAL -->
228
258
  /glab_host
229
259
  /glab_username
230
260
  /glab_token
231
-
232
- <!-- REQUIRED -->
233
- /title
234
-
235
- <!-- OPTIONAL -->
236
261
  /repo
237
262
  /milestone
238
263
  /milestone-start YYYY-MM-DD
239
264
  /milestone-end YYYY-MM-DD
240
265
  /assignee
241
- /label
242
- /estimate
243
- /due YYYY-MM-DD
244
-
245
- <!-- OPTIONAL -->
246
- ## Acceptance Criteria
247
- - [ ]
248
- - [ ]
249
- ## Acceptance Criteria
250
-
251
- <!-- OPTIONAL -->
252
266
  ## Comment
253
267
 
254
268
  ## Comment
255
269
  ```
256
270
 
257
- Every key except `/title` is optional. Leaving a key empty is allowed — empty keys are simply not sent to GitLab. The date keys keep the `YYYY-MM-DD` format in the template and are treated as empty until you replace them.
271
+ Add a `/title <text>` line for each issue before running `itw task`. The parser also supports the optional directives listed below, including `/label`, `/estimate`, `/due` and custom acceptance criteria. Leaving a key empty is allowed — empty keys are simply not sent to GitLab. The date placeholders use `YYYY-MM-DD` and are treated as empty until you replace them.
258
272
 
259
273
  Any text outside the directives becomes the issue description. Create several issues from one file by separating the blocks with a line containing only `===`.
260
274
 
@@ -283,7 +297,7 @@ When no credentials are given, `itw` uses the `.git` directory in the current fo
283
297
 
284
298
  ### Target Repository
285
299
 
286
- With no `/repo`, the target is resolved by walking the current repository's namespace upward looking for a `_pm` project. If several are found you are prompted to pick one.
300
+ The first `/repo` in the file is the file default. Every later block that leaves `/repo` empty uses that value. A block that sets its own `/repo` keeps it and does not change the default for the blocks below. Blocks above the first `/repo`, and a file with no `/repo` at all, are resolved once by walking the current repository's namespace upward looking for a `_pm` project. If several are found you are prompted to pick one, and that choice is reused for the remaining issues that still have no repo.
287
301
 
288
302
  With `/repo`, leading and trailing slashes are stripped automatically, and full URLs or SSH remotes are accepted:
289
303
 
@@ -299,7 +313,7 @@ Milestones, labels and issue titles are matched with a shared fuzzy comparison a
299
313
 
300
314
  - **Milestone** — an existing project or parent-group milestone with the same title is reused; otherwise it is created (with the start/end dates when both are given).
301
315
  - **Label** — a similar existing label is linked and logged in white; a new one is created and logged in green. An empty `/label` is never sent to GitLab.
302
- - **Duplicate issues** — before creating, the target project is searched by title. A match in the same milestone, or an unassigned issue with the same title, is treated as a duplicate and skipped.
316
+ - **Duplicate issues** — before creating, the target project is searched by title. A similar title is treated as a duplicate and skipped only when the milestone and assignees also match. An empty milestone or assignee matches only an issue where that field is also empty.
303
317
 
304
318
  ### Acceptance Criteria and Comments
305
319
 
@@ -72,6 +72,35 @@ itw incrementpatch
72
72
  - `itw incrementrc` — Increment release candidate (staging)
73
73
  - `itw release` — Promote RC to stable release (master)
74
74
 
75
+ ### Timesheet Reporting for Frontend Releases
76
+
77
+ Pass `-tm` to any deployment command to report a merge request to Timesheet before publishing:
78
+
79
+ ```bash
80
+ # Find a specific MR number merged today in the current GitLab group
81
+ itw incrementpatch -tm 110
82
+
83
+ # Choose from today's merged MRs in the terminal
84
+ itw incrementrc -tm
85
+ ```
86
+
87
+ `--tm` and `--tm=110` are also supported. The option is available on `incrementrc`, `incrementpatch`, `incrementminor`, `incrementmajor` and `release`, for frontend projects on their allowed `staging`/`master` branches. Backend projects reject it before authentication or release work.
88
+
89
+ The current group is the full namespace of the origin repository; the search includes its subgroups and all accessible projects, including backend repositories. It uses the existing GitLab login and matches `merged_at` against today's calendar day in the local timezone. The number is the project-local MR number shown in GitLab, such as `!110`. If that number matches several repositories, you must choose one. Without a number, you must choose from the listed MRs even when only one is available. An interactive selection requires a terminal; a unique explicit number works without one. No matching MR stops the release with a message naming the number and group.
90
+
91
+ Configure Timesheet in the builder's root `.env`:
92
+
93
+ ```dotenv
94
+ TIMESHEET_REPORT_URL=https://tm.it-works.io/api/qa-issue-from-merge-request/
95
+ QA_ISSUE_API_KEY=<shared-api-key>
96
+ ```
97
+
98
+ Both values are required and are read only from the `.env` in the builder's root, resolved relative to the package location. The project being released and environment variables do not override this configuration.
99
+
100
+ After the tests and analysis pass, `itw` sends one POST to `TIMESHEET_REPORT_URL`, before creating a tag or changing/publishing the version. The request headers are `X-Api-Key` (the configured API key), `Version` (for example `1.2.3`, without the tag prefix or RC suffix), `Merge-Request-Repo` (the selected MR's `group/project`) and `Merge-Request-Id` (its MR number).
101
+
102
+ An HTTP error stops the release and displays the response's `message` (or `MESSAGE`); non-JSON error responses and connection/timeout failures also stop it with their error details. Reporting is not automatically retried. `--skip-pipeline` still reports to Timesheet, and SSR or multiple production environments report once per release. If a later build or upload fails, the existing Timesheet report is not rolled back. Commands without `-tm` do not search MRs or report to Timesheet.
103
+
75
104
  ### Authentication Commands
76
105
 
77
106
  - `itw login` — Capture and cache a GitLab token (backend also logs into the container registry)
@@ -121,6 +150,8 @@ itw test --target=core.service
121
150
 
122
151
  ### SSR Builds
123
152
 
153
+ On a production frontend deploy (`master`), `itw` looks in `src/environments` for `*.prod.ts` files. One file keeps the existing `build-master` script and uploads `frontend/<version>/dist.tar.gz`. Several files prompt for which one to deploy, with `all` as the last choice. Each selected environment is built with the matching `angular.json` configuration, packaged as `dist-<environment>.tar.gz`, and uploaded before the next one starts, at `frontend/<version>/dist-<environment>.tar.gz`. The version commit then includes that name, for example `version update to v.1.2.3-release (lenslight)`. Choosing `all` lists every name: `version update to v.1.2.3-release (greenterrace, lenslight)`.
154
+
124
155
  Frontend projects scaffolded with `itw ssr-init` build through the SSR npm scripts when `--ssr` is passed:
125
156
  ```bash
126
157
  itw incrementrc --ssr
@@ -190,42 +221,25 @@ Then fill it in and run:
190
221
  itw task --file=TASK.md
191
222
  ```
192
223
 
193
- `task-init` refuses to overwrite an existing `TASK.md`.
224
+ `task-init` refuses to overwrite an existing `TASK.md`. Without `.git` in the current directory, repo and milestone stay empty. With `.git`, it reads the GitLab remote and finds the namespace's `_pm` repositories. A single repository is selected automatically; several prompt for a selection. Milestones from the selected project and its parent groups follow the same selection rule, and the chosen milestone's available start/end dates are filled in. When no milestones exist, the milestone stays empty and the date placeholders are kept.
194
225
 
195
226
  ### Template
196
227
 
197
228
  ```markdown
198
- <!-- OPTIONAL -->
199
229
  /glab_host
200
230
  /glab_username
201
231
  /glab_token
202
-
203
- <!-- REQUIRED -->
204
- /title
205
-
206
- <!-- OPTIONAL -->
207
232
  /repo
208
233
  /milestone
209
234
  /milestone-start YYYY-MM-DD
210
235
  /milestone-end YYYY-MM-DD
211
236
  /assignee
212
- /label
213
- /estimate
214
- /due YYYY-MM-DD
215
-
216
- <!-- OPTIONAL -->
217
- ## Acceptance Criteria
218
- - [ ]
219
- - [ ]
220
- ## Acceptance Criteria
221
-
222
- <!-- OPTIONAL -->
223
237
  ## Comment
224
238
 
225
239
  ## Comment
226
240
  ```
227
241
 
228
- Every key except `/title` is optional. Leaving a key empty is allowed — empty keys are simply not sent to GitLab. The date keys keep the `YYYY-MM-DD` format in the template and are treated as empty until you replace them.
242
+ Add a `/title <text>` line for each issue before running `itw task`. The parser also supports the optional directives listed below, including `/label`, `/estimate`, `/due` and custom acceptance criteria. Leaving a key empty is allowed — empty keys are simply not sent to GitLab. The date placeholders use `YYYY-MM-DD` and are treated as empty until you replace them.
229
243
 
230
244
  Any text outside the directives becomes the issue description. Create several issues from one file by separating the blocks with a line containing only `===`.
231
245
 
@@ -254,7 +268,7 @@ When no credentials are given, `itw` uses the `.git` directory in the current fo
254
268
 
255
269
  ### Target Repository
256
270
 
257
- With no `/repo`, the target is resolved by walking the current repository's namespace upward looking for a `_pm` project. If several are found you are prompted to pick one.
271
+ The first `/repo` in the file is the file default. Every later block that leaves `/repo` empty uses that value. A block that sets its own `/repo` keeps it and does not change the default for the blocks below. Blocks above the first `/repo`, and a file with no `/repo` at all, are resolved once by walking the current repository's namespace upward looking for a `_pm` project. If several are found you are prompted to pick one, and that choice is reused for the remaining issues that still have no repo.
258
272
 
259
273
  With `/repo`, leading and trailing slashes are stripped automatically, and full URLs or SSH remotes are accepted:
260
274
 
@@ -270,7 +284,7 @@ Milestones, labels and issue titles are matched with a shared fuzzy comparison a
270
284
 
271
285
  - **Milestone** — an existing project or parent-group milestone with the same title is reused; otherwise it is created (with the start/end dates when both are given).
272
286
  - **Label** — a similar existing label is linked and logged in white; a new one is created and logged in green. An empty `/label` is never sent to GitLab.
273
- - **Duplicate issues** — before creating, the target project is searched by title. A match in the same milestone, or an unassigned issue with the same title, is treated as a duplicate and skipped.
287
+ - **Duplicate issues** — before creating, the target project is searched by title. A similar title is treated as a duplicate and skipped only when the milestone and assignees also match. An empty milestone or assignee matches only an issue where that field is also empty.
274
288
 
275
289
  ### Acceptance Criteria and Comments
276
290
 
@@ -0,0 +1,63 @@
1
+ import sys
2
+ import fcntl
3
+ import struct
4
+ import termios
5
+ from importlib.metadata import PackageNotFoundError, version as _pkg_version
6
+
7
+ from invoke import Argument, Collection, Program, runners, terminals
8
+
9
+ from itw_python_builder import tasks
10
+
11
+
12
+ # Fix for Python 3.14+: termios.FIONREAD expects a 4-byte (int) buffer.
13
+ # Invoke historically passed a 2-byte buffer (b" ") and unpacked with "h",
14
+ # which causes SystemError: buffer overflow on Python 3.14.
15
+ def _fixed_bytes_to_read(input_):
16
+ if not terminals.WINDOWS and terminals.isatty(input_) and terminals.has_fileno(input_):
17
+ fionread = fcntl.ioctl(input_, termios.FIONREAD, b" ")
18
+ return int(struct.unpack("i", fionread)[0])
19
+ return 1
20
+
21
+
22
+ terminals.bytes_to_read = _fixed_bytes_to_read
23
+ runners.bytes_to_read = _fixed_bytes_to_read
24
+
25
+
26
+ def _get_version() -> str:
27
+ try:
28
+ return _pkg_version('itw_python_builder')
29
+ except PackageNotFoundError:
30
+ return 'unknown'
31
+
32
+
33
+ class ItwProgram(Program):
34
+ def core_args(self):
35
+ args = super().core_args()
36
+ result = []
37
+ for arg in args:
38
+ if 'version' in arg.names:
39
+ result.append(Argument(
40
+ names=('version', 'v'),
41
+ kind=bool,
42
+ default=False,
43
+ help='Show version and exit.',
44
+ ))
45
+ else:
46
+ result.append(arg)
47
+ return result
48
+
49
+
50
+ def normalize_cli_args(argv: list) -> list:
51
+ arguments = []
52
+ for index, argument in enumerate(argv):
53
+ if argument == '--':
54
+ arguments.extend(argv[index:])
55
+ break
56
+ arguments.append('--tm' if argument == '-tm' else argument)
57
+ return arguments
58
+
59
+
60
+ def main():
61
+ namespace = Collection.from_module(tasks)
62
+ program = ItwProgram(namespace=namespace, name='itw', version=_get_version())
63
+ program.run(argv=normalize_cli_args(sys.argv))
@@ -115,14 +115,23 @@ def _issue_milestone_title(issue: dict) -> str:
115
115
  return ''
116
116
 
117
117
 
118
- def _is_duplicate_issue(issue: dict, title: str, milestone: str = None) -> bool:
119
- """True when titles match and the issue is in the target milestone or has none."""
118
+ def is_duplicate_issue(issue: dict, title: str, milestone: str = None, assignee: str = None) -> bool:
119
+ """True when similar titles have the same milestone and assignees."""
120
120
  if not is_similar(title, issue.get('title', '')):
121
121
  return False
122
122
  existing = _issue_milestone_title(issue)
123
- if milestone:
124
- return (not existing) or is_similar(milestone, existing)
125
- return not existing
123
+ if milestone and not is_similar(milestone, existing):
124
+ return False
125
+ if not milestone and existing:
126
+ return False
127
+ expected_assignees = {
128
+ username.lstrip('@').lower()
129
+ for username in re.split(r'[\s,]+', (assignee or '').strip()) if username
130
+ }
131
+ existing_assignees = {
132
+ assigned['username'].lower() for assigned in (issue.get('assignees') or [])
133
+ }
134
+ return expected_assignees == existing_assignees
126
135
 
127
136
 
128
137
  def _list_group_projects(api_host: str, group_path: str, token: str) -> list:
@@ -171,6 +180,10 @@ def get_project_by_path(api_host: str, project_path: str, token: str) -> dict:
171
180
  return _gitlab_api_call(api_host, f'/projects/{encoded}', token)
172
181
 
173
182
 
183
+ def list_project_milestones(api_host: str, project_id: int, token: str) -> list:
184
+ return _gitlab_api_list(api_host, f'/projects/{project_id}/milestones?include_ancestors=true&state=active', token)
185
+
186
+
174
187
  def find_project_milestone(api_host: str, project_id: int, title: str, token: str):
175
188
  """Find a project or ancestor-group milestone by title."""
176
189
  encoded = quote(title, safe='')
@@ -192,8 +205,8 @@ def _list_issues_for_milestone(api_host: str, project_id: int, milestone: str, t
192
205
  )
193
206
 
194
207
 
195
- def find_project_issue(api_host: str, project_id: int, title: str, token: str, milestone: str = None):
196
- """Look for a ~matching title in this milestone, or among issues with no milestone."""
208
+ def find_project_issue(api_host: str, project_id: int, title: str, token: str, milestone: str = None, assignee: str = None):
209
+ """Look for a similar title with the same milestone and assignees."""
197
210
  encoded = quote(title, safe='')
198
211
  searched = _gitlab_api_list(
199
212
  api_host,
@@ -201,16 +214,12 @@ def find_project_issue(api_host: str, project_id: int, title: str, token: str, m
201
214
  token,
202
215
  )
203
216
  for item in searched:
204
- if _is_duplicate_issue(item, title, milestone):
217
+ if is_duplicate_issue(item, title, milestone, assignee):
205
218
  return item
206
219
 
207
220
  for item in _list_issues_for_milestone(api_host, project_id, milestone, token):
208
- if _is_duplicate_issue(item, title, milestone):
221
+ if is_duplicate_issue(item, title, milestone, assignee):
209
222
  return item
210
- if milestone:
211
- for item in _list_issues_for_milestone(api_host, project_id, None, token):
212
- if _is_duplicate_issue(item, title, milestone):
213
- return item
214
223
  return None
215
224
 
216
225