kloship-utils 1.0.0__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 (42) hide show
  1. kloship_utils-1.0.0/.gitignore +26 -0
  2. kloship_utils-1.0.0/LICENSE +21 -0
  3. kloship_utils-1.0.0/PKG-INFO +192 -0
  4. kloship_utils-1.0.0/README.md +146 -0
  5. kloship_utils-1.0.0/pyproject.toml +119 -0
  6. kloship_utils-1.0.0/src/kloship_utils/__init__.py +26 -0
  7. kloship_utils-1.0.0/src/kloship_utils/_version.py +24 -0
  8. kloship_utils-1.0.0/src/kloship_utils/aws/__init__.py +36 -0
  9. kloship_utils-1.0.0/src/kloship_utils/aws/dynamodb.py +376 -0
  10. kloship_utils-1.0.0/src/kloship_utils/aws/s3.py +216 -0
  11. kloship_utils-1.0.0/src/kloship_utils/cella.py +255 -0
  12. kloship_utils-1.0.0/src/kloship_utils/encoding.py +41 -0
  13. kloship_utils-1.0.0/src/kloship_utils/exceptions.py +45 -0
  14. kloship_utils-1.0.0/src/kloship_utils/handle_units.py +136 -0
  15. kloship_utils-1.0.0/src/kloship_utils/helpers.py +51 -0
  16. kloship_utils-1.0.0/src/kloship_utils/py.typed +0 -0
  17. kloship_utils-1.0.0/src/kloship_utils/templates.py +73 -0
  18. kloship_utils-1.0.0/src/kloship_utils/text.py +57 -0
  19. kloship_utils-1.0.0/src/kloship_utils/transfers/__init__.py +11 -0
  20. kloship_utils-1.0.0/src/kloship_utils/transfers/config.py +177 -0
  21. kloship_utils-1.0.0/src/kloship_utils/transfers/ftp.py +97 -0
  22. kloship_utils-1.0.0/src/kloship_utils/transfers/sftp.py +148 -0
  23. kloship_utils-1.0.0/src/kloship_utils/units.py +252 -0
  24. kloship_utils-1.0.0/src/kloship_utils/xml.py +67 -0
  25. kloship_utils-1.0.0/tests/__init__.py +0 -0
  26. kloship_utils-1.0.0/tests/conftest.py +123 -0
  27. kloship_utils-1.0.0/tests/fixtures/carrier_account_config.json +16 -0
  28. kloship_utils-1.0.0/tests/fixtures/handle_units.json +53 -0
  29. kloship_utils-1.0.0/tests/unit/__init__.py +0 -0
  30. kloship_utils-1.0.0/tests/unit/test_cella.py +180 -0
  31. kloship_utils-1.0.0/tests/unit/test_dynamodb.py +198 -0
  32. kloship_utils-1.0.0/tests/unit/test_encoding.py +37 -0
  33. kloship_utils-1.0.0/tests/unit/test_ftp.py +92 -0
  34. kloship_utils-1.0.0/tests/unit/test_handle_units.py +86 -0
  35. kloship_utils-1.0.0/tests/unit/test_helpers.py +29 -0
  36. kloship_utils-1.0.0/tests/unit/test_s3.py +98 -0
  37. kloship_utils-1.0.0/tests/unit/test_sftp.py +155 -0
  38. kloship_utils-1.0.0/tests/unit/test_templates.py +39 -0
  39. kloship_utils-1.0.0/tests/unit/test_text.py +34 -0
  40. kloship_utils-1.0.0/tests/unit/test_transfers_config.py +95 -0
  41. kloship_utils-1.0.0/tests/unit/test_units.py +164 -0
  42. kloship_utils-1.0.0/tests/unit/test_xml.py +46 -0
@@ -0,0 +1,26 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ .venv/
6
+ env*/
7
+
8
+ # Generated by hatch-vcs at build / install time
9
+ src/kloship_utils/_version.py
10
+
11
+ # Build
12
+ build/
13
+ dist/
14
+
15
+ # Tools
16
+ .mypy_cache/
17
+ .ruff_cache/
18
+ .pytest_cache/
19
+ .coverage
20
+ coverage.xml
21
+ htmlcov/
22
+ .task/
23
+
24
+ # IDE
25
+ .vscode/
26
+ .idea/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Groupe Klocel
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,192 @@
1
+ Metadata-Version: 2.5
2
+ Name: kloship-utils
3
+ Version: 1.0.0
4
+ Summary: Helper library for KloShip.
5
+ Project-URL: Homepage, https://www.klocel.com
6
+ Author-email: Guillaume Candau <guillaume.candau@klocel.com>
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Keywords: aws-lambda,edi,klocel,kloship,shipping,zpl
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Operating System :: OS Independent
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3 :: Only
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Topic :: Software Development :: Libraries
19
+ Classifier: Typing :: Typed
20
+ Requires-Python: >=3.11
21
+ Requires-Dist: jinja2>=3.1
22
+ Requires-Dist: requests>=2.31
23
+ Requires-Dist: unidecode>=1.3
24
+ Provides-Extra: all
25
+ Requires-Dist: boto3>=1.28; extra == 'all'
26
+ Requires-Dist: paramiko>=3.4; extra == 'all'
27
+ Provides-Extra: aws
28
+ Requires-Dist: boto3>=1.28; extra == 'aws'
29
+ Provides-Extra: dev
30
+ Requires-Dist: boto3-stubs[dynamodb,s3]>=1.28; extra == 'dev'
31
+ Requires-Dist: boto3>=1.28; extra == 'dev'
32
+ Requires-Dist: build>=1.2; extra == 'dev'
33
+ Requires-Dist: moto[dynamodb,s3]>=5.0; extra == 'dev'
34
+ Requires-Dist: mypy>=1.10; extra == 'dev'
35
+ Requires-Dist: paramiko>=3.4; extra == 'dev'
36
+ Requires-Dist: pytest-cov>=5.0; extra == 'dev'
37
+ Requires-Dist: pytest>=8.0; extra == 'dev'
38
+ Requires-Dist: responses>=0.25; extra == 'dev'
39
+ Requires-Dist: ruff>=0.6; extra == 'dev'
40
+ Requires-Dist: twine>=5.1; extra == 'dev'
41
+ Requires-Dist: types-paramiko>=3.4; extra == 'dev'
42
+ Requires-Dist: types-requests>=2.31; extra == 'dev'
43
+ Provides-Extra: sftp
44
+ Requires-Dist: paramiko>=3.4; extra == 'sftp'
45
+ Description-Content-Type: text/markdown
46
+
47
+ # kloship-utils
48
+
49
+ `kloship-utils` is a helper library for [KloShip](https://www.klocel.com).
50
+
51
+ ## Installation
52
+
53
+ Requires Python 3.11 or later.
54
+
55
+ ```bash
56
+ pip install kloship-utils # core: encoding, units, text, templates, xml, handle units, CELLA, FTP
57
+ pip install "kloship-utils[sftp]" # + SFTP uploads (paramiko)
58
+ pip install "kloship-utils[aws]" # + boto3, for the S3 / DynamoDB helpers outside AWS Lambda
59
+ ```
60
+
61
+ `boto3` is not a mandatory dependency: the AWS Lambda Python runtime already provides it.
62
+
63
+ ### In an AWS Lambda layer
64
+
65
+ Add the package to the layer `requirements.txt`, pinned to an exact version:
66
+
67
+ ```text
68
+ kloship-utils[sftp]==0.1.0
69
+ ```
70
+
71
+ Every dependency ships `aarch64` wheels, so the package works with `arm64` Lambdas.
72
+
73
+ ## Modules
74
+
75
+ | Module | Content |
76
+ |---|---|
77
+ | `kloship_utils.encoding` | `to_base64_gzip_json`, `from_base64_gzip_json`: payloads exchanged between Step Functions and Lambdas |
78
+ | `kloship_utils.helpers` | `to_list`, `empty_if_none`, `chunks`, `get_path` |
79
+ | `kloship_utils.units` | `convert_SI` (length, volume, weight, liquid, dates), `convert_date`, `convert_values` |
80
+ | `kloship_utils.text` | `strip_diacritics`, `strip_diacritics_in`, `replace_special_chars` |
81
+ | `kloship_utils.templates` | `render_template`, `render_zpl_label`, `split_zpl` (Jinja2) |
82
+ | `kloship_utils.xml` | `dict_to_xml`, `to_xml_string` (attributes, lists, CDATA) |
83
+ | `kloship_utils.handle_units` | `Status`, `global_group_id`, `global_group_id2`, `group_by_delivery`, `next_index_in_order`, `delete_attachments_from_result`, `clear_fields` |
84
+ | `kloship_utils.aws.s3` | `build_key`, `put_file`, `get_file`, `save_label`, `save_shipment_file`, file name helpers |
85
+ | `kloship_utils.aws.dynamodb` | HandleUnit lookups, `increment_counter`, `get_parameter`, `get_carrier_account_config`, `get_conversion`, `get_packaging_conversion`, `execute_statement_all`, `batch_execute` |
86
+ | `kloship_utils.cella` | `CellaClient`, `get_rule_result`, `get_rule_result_from_kloship_front`, `pdf_to_zpl` |
87
+ | `kloship_utils.transfers` | `TransferConfig`, `TunnelConfig`, `upload_ftp`, `upload_sftp` |
88
+ | `kloship_utils.exceptions` | `KloshipUtilsError` and its subclasses |
89
+
90
+ ### Encoding
91
+
92
+ ```python
93
+ from kloship_utils.encoding import from_base64_gzip_json, to_base64_gzip_json
94
+
95
+ def lambda_handler(event, context):
96
+ handle_units = from_base64_gzip_json(event["compressed_handle_units"])
97
+ ...
98
+ return {"compressed_handle_units": to_base64_gzip_json(enriched_handle_units)}
99
+ ```
100
+
101
+ Pass `default=str` to `to_base64_gzip_json` to serialize the `Decimal` values returned by DynamoDB.
102
+
103
+ ### Units and dates
104
+
105
+ ```python
106
+ from kloship_utils.units import convert_SI, convert_date
107
+
108
+ convert_SI(hu["WEIGHT"]["#text"], "weight", hu["WEIGHT"]["@format"], "kg") # "10.05" (2 decimals)
109
+ convert_SI("1234", "length", "mm", "cm", number_decimal=0) # "123"
110
+ convert_SI("1234", "length", "mm", "m", number_decimal=None) # "1.234" (no rounding)
111
+ convert_SI("2024/01/31", "date", "YYYY/MM/DD", "%d.%m.%Y") # "31.01.2024"
112
+ convert_date("2024-01-31 08:05:00", "YYYY-MM-DD HH:MI:SS", "CCYYMMDDHHMM") # "202401310805"
113
+ ```
114
+
115
+ Date formats accept KloShip tokens (`yyyy`, `ccyy`, `yy`, `mm`, `dd`, `hh`, `mi`/`ii`, `ss`; `mm` after `hh` means
116
+ minutes) or `strftime` patterns.
117
+
118
+ ### Labels
119
+
120
+ ```python
121
+ from kloship_utils.templates import render_zpl_label, split_zpl
122
+ from kloship_utils.aws.s3 import save_label
123
+
124
+ zpl = render_zpl_label(handle_unit, config, "layout_label.zpl") # templates/ directory of the Lambda
125
+ handle_unit["label"] = split_zpl(zpl) # {"header", "body", "footer"}
126
+ handle_unit["KLOSHIP_LABEL_FILENAME"] = save_label(
127
+ handle_unit, account_id, config, zpl, extension="zpl", content_type="x-application/zpl", carrier="ACME"
128
+ )
129
+ ```
130
+
131
+ ### S3
132
+
133
+ ```python
134
+ from kloship_utils.aws.s3 import save_shipment_file, shipment_file_name
135
+
136
+ file_name = shipment_file_name(config, "edi") # 20240131_080509_42.edi
137
+ save_shipment_file(
138
+ edi, account_id, config, file_name,
139
+ content_type="application/EDI-EDIFACT", carrier="ACME",
140
+ encoding="ISO-8859-1", content_encoding="ISO-8859-1",
141
+ )
142
+ ```
143
+
144
+ Keys follow the KloShip layout `{account}/{@senderCodeTDM}/{@serviceTagTDM}/{YYYY}/{MM}/{DD}/{file}`, in the
145
+ `STANDARD_IA` storage class. Buckets default to the `LABELS_BUCKET` / `SHIPMENT_BUCKET` environment variables.
146
+
147
+ ### DynamoDB
148
+
149
+ ```python
150
+ from kloship_utils.aws import dynamodb
151
+
152
+ handle_units = dynamodb.get_handle_units_by_global_group_id(account_id, config) # PRE-SHIPPED / SHIPPED HUs
153
+ number = dynamodb.increment_counter(config, parameter_name=config.get("ParameterNameHUCounter"))
154
+ packaging = dynamodb.get_packaging_conversion(hu["PACKAGING"], config, default=config.get("DefaultPackaging"))
155
+ ```
156
+
157
+ Table names default to the standard environment variables (`HANDLE_UNIT_TABLE_NAME`,
158
+ `CARRIER_ACCOUNT_CONFIG_TABLE_NAME`, `PARAMETERS_TABLE_NAME`, `CONVERSIONS_TABLE_NAME`) and can be given explicitly.
159
+ All PartiQL statements are parameterized.
160
+
161
+ ### CELLA rules
162
+
163
+ ```python
164
+ from kloship_utils.cella import get_rule_result
165
+
166
+ values = get_rule_result(
167
+ config["CreateLabel"]["FrontendConversion"], # Url, WarehouseWorkerUsername, WarehouseWorkerPwd, WarehouseId, StockOwnerId
168
+ rule_config, # Name + Exit [{name, type, defaultValue}]
169
+ {"packagingDescription": hu["PACKAGING"]},
170
+ )
171
+ ```
172
+
173
+ ### FTP / SFTP
174
+
175
+ ```python
176
+ from kloship_utils.transfers import TransferConfig, TunnelConfig, upload_sftp
177
+
178
+ sftp = TransferConfig.from_carrier_config(config["Shipment"]["Sftp"])
179
+ tunnel = TunnelConfig.from_carrier_config(config["Shipment"]["TunnelSSH"], password_base64=True)
180
+ upload_sftp(sftp, file_name, edi, tunnel=tunnel) # raises TransferError (with .code 401/402/404) on failure
181
+ ```
182
+
183
+ `TransferConfig.from_carrier_config` reads the usual configuration keys whatever their case (`Host`, `Port`, `Login`,
184
+ `Password`, `RemotePath`, `EDIFileEncoding`, `UseCnOptsHostkeys`, `ParamikoKeyData`, `ParamikoSignVerifySSHData`).
185
+
186
+ ## Versioning
187
+
188
+ The package follows [Semantic Versioning](https://semver.org). Pin an exact version in your requirements.
189
+
190
+ ## License
191
+
192
+ MIT License, © Groupe Klocel.
@@ -0,0 +1,146 @@
1
+ # kloship-utils
2
+
3
+ `kloship-utils` is a helper library for [KloShip](https://www.klocel.com).
4
+
5
+ ## Installation
6
+
7
+ Requires Python 3.11 or later.
8
+
9
+ ```bash
10
+ pip install kloship-utils # core: encoding, units, text, templates, xml, handle units, CELLA, FTP
11
+ pip install "kloship-utils[sftp]" # + SFTP uploads (paramiko)
12
+ pip install "kloship-utils[aws]" # + boto3, for the S3 / DynamoDB helpers outside AWS Lambda
13
+ ```
14
+
15
+ `boto3` is not a mandatory dependency: the AWS Lambda Python runtime already provides it.
16
+
17
+ ### In an AWS Lambda layer
18
+
19
+ Add the package to the layer `requirements.txt`, pinned to an exact version:
20
+
21
+ ```text
22
+ kloship-utils[sftp]==0.1.0
23
+ ```
24
+
25
+ Every dependency ships `aarch64` wheels, so the package works with `arm64` Lambdas.
26
+
27
+ ## Modules
28
+
29
+ | Module | Content |
30
+ |---|---|
31
+ | `kloship_utils.encoding` | `to_base64_gzip_json`, `from_base64_gzip_json`: payloads exchanged between Step Functions and Lambdas |
32
+ | `kloship_utils.helpers` | `to_list`, `empty_if_none`, `chunks`, `get_path` |
33
+ | `kloship_utils.units` | `convert_SI` (length, volume, weight, liquid, dates), `convert_date`, `convert_values` |
34
+ | `kloship_utils.text` | `strip_diacritics`, `strip_diacritics_in`, `replace_special_chars` |
35
+ | `kloship_utils.templates` | `render_template`, `render_zpl_label`, `split_zpl` (Jinja2) |
36
+ | `kloship_utils.xml` | `dict_to_xml`, `to_xml_string` (attributes, lists, CDATA) |
37
+ | `kloship_utils.handle_units` | `Status`, `global_group_id`, `global_group_id2`, `group_by_delivery`, `next_index_in_order`, `delete_attachments_from_result`, `clear_fields` |
38
+ | `kloship_utils.aws.s3` | `build_key`, `put_file`, `get_file`, `save_label`, `save_shipment_file`, file name helpers |
39
+ | `kloship_utils.aws.dynamodb` | HandleUnit lookups, `increment_counter`, `get_parameter`, `get_carrier_account_config`, `get_conversion`, `get_packaging_conversion`, `execute_statement_all`, `batch_execute` |
40
+ | `kloship_utils.cella` | `CellaClient`, `get_rule_result`, `get_rule_result_from_kloship_front`, `pdf_to_zpl` |
41
+ | `kloship_utils.transfers` | `TransferConfig`, `TunnelConfig`, `upload_ftp`, `upload_sftp` |
42
+ | `kloship_utils.exceptions` | `KloshipUtilsError` and its subclasses |
43
+
44
+ ### Encoding
45
+
46
+ ```python
47
+ from kloship_utils.encoding import from_base64_gzip_json, to_base64_gzip_json
48
+
49
+ def lambda_handler(event, context):
50
+ handle_units = from_base64_gzip_json(event["compressed_handle_units"])
51
+ ...
52
+ return {"compressed_handle_units": to_base64_gzip_json(enriched_handle_units)}
53
+ ```
54
+
55
+ Pass `default=str` to `to_base64_gzip_json` to serialize the `Decimal` values returned by DynamoDB.
56
+
57
+ ### Units and dates
58
+
59
+ ```python
60
+ from kloship_utils.units import convert_SI, convert_date
61
+
62
+ convert_SI(hu["WEIGHT"]["#text"], "weight", hu["WEIGHT"]["@format"], "kg") # "10.05" (2 decimals)
63
+ convert_SI("1234", "length", "mm", "cm", number_decimal=0) # "123"
64
+ convert_SI("1234", "length", "mm", "m", number_decimal=None) # "1.234" (no rounding)
65
+ convert_SI("2024/01/31", "date", "YYYY/MM/DD", "%d.%m.%Y") # "31.01.2024"
66
+ convert_date("2024-01-31 08:05:00", "YYYY-MM-DD HH:MI:SS", "CCYYMMDDHHMM") # "202401310805"
67
+ ```
68
+
69
+ Date formats accept KloShip tokens (`yyyy`, `ccyy`, `yy`, `mm`, `dd`, `hh`, `mi`/`ii`, `ss`; `mm` after `hh` means
70
+ minutes) or `strftime` patterns.
71
+
72
+ ### Labels
73
+
74
+ ```python
75
+ from kloship_utils.templates import render_zpl_label, split_zpl
76
+ from kloship_utils.aws.s3 import save_label
77
+
78
+ zpl = render_zpl_label(handle_unit, config, "layout_label.zpl") # templates/ directory of the Lambda
79
+ handle_unit["label"] = split_zpl(zpl) # {"header", "body", "footer"}
80
+ handle_unit["KLOSHIP_LABEL_FILENAME"] = save_label(
81
+ handle_unit, account_id, config, zpl, extension="zpl", content_type="x-application/zpl", carrier="ACME"
82
+ )
83
+ ```
84
+
85
+ ### S3
86
+
87
+ ```python
88
+ from kloship_utils.aws.s3 import save_shipment_file, shipment_file_name
89
+
90
+ file_name = shipment_file_name(config, "edi") # 20240131_080509_42.edi
91
+ save_shipment_file(
92
+ edi, account_id, config, file_name,
93
+ content_type="application/EDI-EDIFACT", carrier="ACME",
94
+ encoding="ISO-8859-1", content_encoding="ISO-8859-1",
95
+ )
96
+ ```
97
+
98
+ Keys follow the KloShip layout `{account}/{@senderCodeTDM}/{@serviceTagTDM}/{YYYY}/{MM}/{DD}/{file}`, in the
99
+ `STANDARD_IA` storage class. Buckets default to the `LABELS_BUCKET` / `SHIPMENT_BUCKET` environment variables.
100
+
101
+ ### DynamoDB
102
+
103
+ ```python
104
+ from kloship_utils.aws import dynamodb
105
+
106
+ handle_units = dynamodb.get_handle_units_by_global_group_id(account_id, config) # PRE-SHIPPED / SHIPPED HUs
107
+ number = dynamodb.increment_counter(config, parameter_name=config.get("ParameterNameHUCounter"))
108
+ packaging = dynamodb.get_packaging_conversion(hu["PACKAGING"], config, default=config.get("DefaultPackaging"))
109
+ ```
110
+
111
+ Table names default to the standard environment variables (`HANDLE_UNIT_TABLE_NAME`,
112
+ `CARRIER_ACCOUNT_CONFIG_TABLE_NAME`, `PARAMETERS_TABLE_NAME`, `CONVERSIONS_TABLE_NAME`) and can be given explicitly.
113
+ All PartiQL statements are parameterized.
114
+
115
+ ### CELLA rules
116
+
117
+ ```python
118
+ from kloship_utils.cella import get_rule_result
119
+
120
+ values = get_rule_result(
121
+ config["CreateLabel"]["FrontendConversion"], # Url, WarehouseWorkerUsername, WarehouseWorkerPwd, WarehouseId, StockOwnerId
122
+ rule_config, # Name + Exit [{name, type, defaultValue}]
123
+ {"packagingDescription": hu["PACKAGING"]},
124
+ )
125
+ ```
126
+
127
+ ### FTP / SFTP
128
+
129
+ ```python
130
+ from kloship_utils.transfers import TransferConfig, TunnelConfig, upload_sftp
131
+
132
+ sftp = TransferConfig.from_carrier_config(config["Shipment"]["Sftp"])
133
+ tunnel = TunnelConfig.from_carrier_config(config["Shipment"]["TunnelSSH"], password_base64=True)
134
+ upload_sftp(sftp, file_name, edi, tunnel=tunnel) # raises TransferError (with .code 401/402/404) on failure
135
+ ```
136
+
137
+ `TransferConfig.from_carrier_config` reads the usual configuration keys whatever their case (`Host`, `Port`, `Login`,
138
+ `Password`, `RemotePath`, `EDIFileEncoding`, `UseCnOptsHostkeys`, `ParamikoKeyData`, `ParamikoSignVerifySSHData`).
139
+
140
+ ## Versioning
141
+
142
+ The package follows [Semantic Versioning](https://semver.org). Pin an exact version in your requirements.
143
+
144
+ ## License
145
+
146
+ MIT License, © Groupe Klocel.
@@ -0,0 +1,119 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.24", "hatch-vcs>=0.4"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "kloship-utils"
7
+ dynamic = ["version"]
8
+ description = "Helper library for KloShip."
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ authors = [{ name = "Guillaume Candau", email = "guillaume.candau@klocel.com" }]
14
+ keywords = ["kloship", "klocel", "shipping", "aws-lambda", "zpl", "edi"]
15
+ classifiers = [
16
+ "Development Status :: 4 - Beta",
17
+ "Intended Audience :: Developers",
18
+ "Operating System :: OS Independent",
19
+ "Programming Language :: Python :: 3",
20
+ "Programming Language :: Python :: 3 :: Only",
21
+ "Programming Language :: Python :: 3.11",
22
+ "Programming Language :: Python :: 3.12",
23
+ "Programming Language :: Python :: 3.13",
24
+ "Topic :: Software Development :: Libraries",
25
+ "Typing :: Typed",
26
+ ]
27
+ dependencies = [
28
+ "requests>=2.31",
29
+ "Jinja2>=3.1",
30
+ "Unidecode>=1.3",
31
+ ]
32
+
33
+ [project.optional-dependencies]
34
+ # boto3 is provided by the AWS Lambda runtime: only install this extra outside Lambda.
35
+ aws = ["boto3>=1.28"]
36
+ sftp = ["paramiko>=3.4"]
37
+ all = ["kloship-utils[aws,sftp]"]
38
+ dev = [
39
+ "kloship-utils[all]",
40
+ "build>=1.2",
41
+ "moto[dynamodb,s3]>=5.0",
42
+ "mypy>=1.10",
43
+ "pytest>=8.0",
44
+ "pytest-cov>=5.0",
45
+ "responses>=0.25",
46
+ "ruff>=0.6",
47
+ "twine>=5.1",
48
+ "boto3-stubs[dynamodb,s3]>=1.28",
49
+ "types-paramiko>=3.4",
50
+ "types-requests>=2.31",
51
+ ]
52
+
53
+ [project.urls]
54
+ Homepage = "https://www.klocel.com"
55
+
56
+ [tool.hatch.version]
57
+ source = "vcs"
58
+
59
+ [tool.hatch.version.raw-options]
60
+ # Lets the package build from a checkout without tags (e.g. a fresh clone before the first release).
61
+ fallback_version = "0.0.0"
62
+
63
+ [tool.hatch.build.hooks.vcs]
64
+ version-file = "src/kloship_utils/_version.py"
65
+
66
+ [tool.hatch.build.targets.wheel]
67
+ packages = ["src/kloship_utils"]
68
+
69
+ [tool.hatch.build.targets.sdist]
70
+ # Only what the public package needs: internal docs (docs/, CLAUDE.md, CONTRIBUTING.md) are not published.
71
+ include = ["src/kloship_utils", "tests", "README.md", "LICENSE"]
72
+
73
+ [tool.ruff]
74
+ line-length = 120
75
+ target-version = "py311"
76
+ src = ["src", "tests"]
77
+ extend-exclude = ["src/kloship_utils/_version.py"]
78
+
79
+ [tool.ruff.lint]
80
+ select = ["E", "W", "F", "I", "B", "UP", "N", "SIM", "C4", "RUF", "PL", "PT"]
81
+ ignore = [
82
+ "PLR0913", # backward-compatible signatures take many arguments
83
+ "PLR2004", # magic values are fine in tests and unit tables
84
+ "PLR0917", # legacy-compatible signatures take many positional arguments
85
+ "N818", # legacy exception names (ConversionNotFound...) are kept for compatibility
86
+ ]
87
+
88
+ [tool.ruff.lint.per-file-ignores]
89
+ # Legacy names are kept on purpose, for backward compatibility.
90
+ "src/kloship_utils/units.py" = ["N802"]
91
+ "src/kloship_utils/cella.py" = ["N803"]
92
+ "tests/**" = ["PLR0915", "N802", "S101"]
93
+
94
+ [tool.ruff.lint.isort]
95
+ known-first-party = ["kloship_utils"]
96
+
97
+ [tool.mypy]
98
+ python_version = "3.11"
99
+ strict = true
100
+ warn_unreachable = true
101
+ files = ["src"]
102
+
103
+ [[tool.mypy.overrides]]
104
+ module = ["unidecode.*", "moto.*"]
105
+ ignore_missing_imports = true
106
+
107
+ [tool.pytest.ini_options]
108
+ testpaths = ["tests"]
109
+ addopts = "-ra --strict-markers"
110
+
111
+ [tool.coverage.run]
112
+ source = ["kloship_utils"]
113
+ branch = true
114
+ omit = ["*/_version.py"]
115
+
116
+ [tool.coverage.report]
117
+ show_missing = true
118
+ skip_covered = false
119
+ exclude_also = ["if TYPE_CHECKING:", "raise NotImplementedError"]
@@ -0,0 +1,26 @@
1
+ """Shared utilities for KloShip carrier integrations.
2
+
3
+ The package is split into small, independent modules so that a carrier Lambda only imports
4
+ (and therefore only needs the dependencies of) what it uses:
5
+
6
+ * :mod:`kloship_utils.encoding` - base64/gzip/JSON payload helpers used between Step Functions and Lambdas
7
+ * :mod:`kloship_utils.helpers` - tiny generic helpers (``to_list``, ``chunks``...)
8
+ * :mod:`kloship_utils.units` - unit (length, volume, weight, liquid) and date conversions
9
+ * :mod:`kloship_utils.text` - diacritics removal and special characters replacement
10
+ * :mod:`kloship_utils.templates` - Jinja2 rendering of ZPL / XML / EDI templates
11
+ * :mod:`kloship_utils.xml` - dict to XML conversion
12
+ * :mod:`kloship_utils.handle_units` - HandleUnit helpers (group ids, grouping, statuses)
13
+ * :mod:`kloship_utils.aws.s3` - archiving of labels, documents and EDI files on S3
14
+ * :mod:`kloship_utils.aws.dynamodb` - HandleUnit lookups, counters and conversions in DynamoDB
15
+ * :mod:`kloship_utils.cella` - CELLA (KloShip front) GraphQL client: rules execution, PDF to ZPL
16
+ * :mod:`kloship_utils.transfers` - FTP and SFTP uploads (optionally through an SSH jump host)
17
+ """
18
+
19
+ from importlib.metadata import PackageNotFoundError, version
20
+
21
+ try:
22
+ __version__ = version("kloship-utils")
23
+ except PackageNotFoundError: # pragma: no cover - only when running from a raw source tree
24
+ __version__ = "0.0.0"
25
+
26
+ __all__ = ["__version__"]
@@ -0,0 +1,24 @@
1
+ # file generated by vcs-versioning
2
+ # don't change, don't track in version control
3
+ from __future__ import annotations
4
+
5
+ __all__ = [
6
+ "__version__",
7
+ "__version_tuple__",
8
+ "version",
9
+ "version_tuple",
10
+ "__commit_id__",
11
+ "commit_id",
12
+ ]
13
+
14
+ version: str
15
+ __version__: str
16
+ __version_tuple__: tuple[int | str, ...]
17
+ version_tuple: tuple[int | str, ...]
18
+ commit_id: str | None
19
+ __commit_id__: str | None
20
+
21
+ __version__ = version = '1.0.0'
22
+ __version_tuple__ = version_tuple = (1, 0, 0)
23
+
24
+ __commit_id__ = commit_id = None
@@ -0,0 +1,36 @@
1
+ """AWS helpers (S3, DynamoDB).
2
+
3
+ ``boto3`` is not a mandatory dependency of kloship-utils because the AWS Lambda Python runtime already provides
4
+ it. Outside Lambda, install the ``aws`` extra: ``pip install "kloship-utils[aws]"``.
5
+ """
6
+
7
+ import os
8
+ from typing import Any
9
+
10
+ from kloship_utils.exceptions import ConfigurationError
11
+
12
+
13
+ def require_env(name: str, value: str | None = None) -> str:
14
+ """Return ``value`` when given, else the ``name`` environment variable.
15
+
16
+ Raises:
17
+ ConfigurationError: neither ``value`` nor the environment variable is set.
18
+ """
19
+ if value:
20
+ return value
21
+ try:
22
+ return os.environ[name]
23
+ except KeyError:
24
+ raise ConfigurationError(f"Environment variable {name} is not set") from None
25
+
26
+
27
+ def boto3_module() -> Any:
28
+ """Import ``boto3`` lazily, with a helpful message when it is missing."""
29
+ try:
30
+ import boto3 # noqa: PLC0415 - lazy import: boto3 is optional (provided by the Lambda runtime)
31
+ except ImportError as error: # pragma: no cover - boto3 is installed in the test environment
32
+ raise ImportError(
33
+ "boto3 is required by kloship_utils.aws: it is provided by the AWS Lambda runtime, "
34
+ 'install "kloship-utils[aws]" elsewhere.'
35
+ ) from error
36
+ return boto3