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.
- kloship_utils-1.0.0/.gitignore +26 -0
- kloship_utils-1.0.0/LICENSE +21 -0
- kloship_utils-1.0.0/PKG-INFO +192 -0
- kloship_utils-1.0.0/README.md +146 -0
- kloship_utils-1.0.0/pyproject.toml +119 -0
- kloship_utils-1.0.0/src/kloship_utils/__init__.py +26 -0
- kloship_utils-1.0.0/src/kloship_utils/_version.py +24 -0
- kloship_utils-1.0.0/src/kloship_utils/aws/__init__.py +36 -0
- kloship_utils-1.0.0/src/kloship_utils/aws/dynamodb.py +376 -0
- kloship_utils-1.0.0/src/kloship_utils/aws/s3.py +216 -0
- kloship_utils-1.0.0/src/kloship_utils/cella.py +255 -0
- kloship_utils-1.0.0/src/kloship_utils/encoding.py +41 -0
- kloship_utils-1.0.0/src/kloship_utils/exceptions.py +45 -0
- kloship_utils-1.0.0/src/kloship_utils/handle_units.py +136 -0
- kloship_utils-1.0.0/src/kloship_utils/helpers.py +51 -0
- kloship_utils-1.0.0/src/kloship_utils/py.typed +0 -0
- kloship_utils-1.0.0/src/kloship_utils/templates.py +73 -0
- kloship_utils-1.0.0/src/kloship_utils/text.py +57 -0
- kloship_utils-1.0.0/src/kloship_utils/transfers/__init__.py +11 -0
- kloship_utils-1.0.0/src/kloship_utils/transfers/config.py +177 -0
- kloship_utils-1.0.0/src/kloship_utils/transfers/ftp.py +97 -0
- kloship_utils-1.0.0/src/kloship_utils/transfers/sftp.py +148 -0
- kloship_utils-1.0.0/src/kloship_utils/units.py +252 -0
- kloship_utils-1.0.0/src/kloship_utils/xml.py +67 -0
- kloship_utils-1.0.0/tests/__init__.py +0 -0
- kloship_utils-1.0.0/tests/conftest.py +123 -0
- kloship_utils-1.0.0/tests/fixtures/carrier_account_config.json +16 -0
- kloship_utils-1.0.0/tests/fixtures/handle_units.json +53 -0
- kloship_utils-1.0.0/tests/unit/__init__.py +0 -0
- kloship_utils-1.0.0/tests/unit/test_cella.py +180 -0
- kloship_utils-1.0.0/tests/unit/test_dynamodb.py +198 -0
- kloship_utils-1.0.0/tests/unit/test_encoding.py +37 -0
- kloship_utils-1.0.0/tests/unit/test_ftp.py +92 -0
- kloship_utils-1.0.0/tests/unit/test_handle_units.py +86 -0
- kloship_utils-1.0.0/tests/unit/test_helpers.py +29 -0
- kloship_utils-1.0.0/tests/unit/test_s3.py +98 -0
- kloship_utils-1.0.0/tests/unit/test_sftp.py +155 -0
- kloship_utils-1.0.0/tests/unit/test_templates.py +39 -0
- kloship_utils-1.0.0/tests/unit/test_text.py +34 -0
- kloship_utils-1.0.0/tests/unit/test_transfers_config.py +95 -0
- kloship_utils-1.0.0/tests/unit/test_units.py +164 -0
- 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
|