Skip to content

Commit aa17664

Browse files
danh91danh91
authored
Merge pull request #97 from PurplShip/standardize-carrier-option-definitions
[feature] self-documented carrier option definition
2 parents 40865e6 + 14f715c commit aa17664

File tree

55 files changed

+2360
-1222
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

55 files changed

+2360
-1222
lines changed

‎.templates/extensions/carrier/pyproject.toml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[tool.poetry]
22
name = "purplship.[carrier]"
3-
version = "2021.1"
3+
version = "[version]"
44
homepage="https://sdk.purplship.com"
55
repository="https://github.com/PurplShip/purplship"
66
description = "Purplship - [Carrier] Shipping Extension"
@@ -17,6 +17,7 @@ classifiers=[
1717

1818
[tool.poetry.dependencies]
1919
python = "^3.6"
20+
"purplship" = ""
2021
"carrier.carrier" = "[version]"
2122

2223
[tool.poetry.dev-dependencies]

‎.templates/extensions/carrier/setup.py‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
"""Warning: This setup.py is only there for git install until poetry support git subdirectory"""
2+
3+
from setuptools import setup, find_namespace_packages
4+
5+
setup(
6+
name='purplship.[carrier]',
7+
version='[version]',
8+
license='LGPLv3',
9+
packages=find_namespace_packages(),
10+
install_requires=['purplship', 'carrier.carrier_name'],
11+
zip_safe=False,
12+
)

‎cli.py‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -45,9 +45,9 @@
4545
{% for key, value in option_mappers.items() %}
4646
#### {{ mappers[key]["label"] }}
4747
48-
| Code | Identifier
49-
| --- | ---
50-
{% for code, name in value.items() %}| `{{ code }}` | {{ name }}
48+
| Code | Identifier | Description
49+
| --- | --- | ---
50+
{% for code, spec in value.items() %}| `{{ code }}` | {{ spec.key }} | {{ spec.type }}
5151
{% endfor %}
5252
{% endfor %}
5353
''')
@@ -155,7 +155,12 @@ def cli():
155155

156156
@cli.command()
157157
def generate_shipment_options():
158-
click.echo(SHIPMENT_OPTIONS_TEMPLATE.render(option_mappers=REFERENCES['options'], mappers=PROVIDERS_DATA))
158+
click.echo(
159+
SHIPMENT_OPTIONS_TEMPLATE.render(
160+
option_mappers=REFERENCES['options'],
161+
mappers=PROVIDERS_DATA
162+
).replace("<class '", "`").replace("'>", "`")
163+
)
159164

160165

161166
@cli.command()

docs/development/contributing.md renamed to docs/contributing.md

File renamed without changes.

‎docs/guide/address.md‎

Lines changed: 100 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,107 @@ from purplship.core.models import AddressValidationRequest
66

77
request = AddressValidationRequest(...)
88

9-
validation, messages = purplship.Address.validate(request).from_(gateway).parse()
9+
validation, messages = purplship.Address.validate(request).from_(carrier_gateway).parse()
1010
```
1111

12+
### Parameters
1213

13-
!!! info
14-
Checkout the reference for more details on the `AddressValidationRequest` and
15-
the returned `AddressValidationDetails` and potential `Message` in case of
16-
failure or notice
17-
18-
[REFERENCES](/references)
1914

15+
#### AddressValidationRequest
16+
17+
| Name | Type | Description
18+
| --- | --- | --- |
19+
| `address` | [Address](#address) | **required**
20+
21+
22+
#### Address
23+
24+
| Name | Type | Description
25+
| --- | --- | --- |
26+
| `id` | `str` |
27+
| `postal_code` | `str` |
28+
| `city` | `str` |
29+
| `person_name` | `str` |
30+
| `company_name` | `str` |
31+
| `country_code` | `str` |
32+
| `email` | `str` |
33+
| `phone_number` | `str` |
34+
| `state_code` | `str` |
35+
| `suburb` | `str` |
36+
| `residential` | `bool` |
37+
| `address_line1` | `str` |
38+
| `address_line2` | `str` |
39+
| `federal_tax_id` | `str` |
40+
| `state_tax_id` | `str` |
41+
42+
43+
### Response
44+
45+
46+
#### AddressValidationDetails
47+
48+
| Name | Type | Description
49+
| --- | --- | --- |
50+
| `carrier_name` | `str` | **required**
51+
| `carrier_id` | `str` | **required**
52+
| `success` | `bool` | **required**
53+
| `complete_address` | [Address](#address) |
54+
55+
56+
#### Message
57+
58+
| Name | Type | Description
59+
| --- | --- | --- |
60+
| `carrier_name` | `str` | **required**
61+
| `carrier_id` | `str` | **required**
62+
| `message` | Union[str, Any] |
63+
| `code` | `str` |
64+
| `details` | `dict` |
65+
66+
67+
---
68+
69+
### Code sample
70+
71+
```python
72+
import purplship
73+
from purplship.core.models import AddressValidationRequest, Address
74+
75+
address = Address(
76+
postal_code="V6M2V9",
77+
city="Vancouver",
78+
country_code="CA",
79+
state_code="BC",
80+
address_line1="5840 Oak St"
81+
)
82+
83+
request = purplship.Address.validate(
84+
AddressValidationRequest(address=address)
85+
)
86+
87+
tracking_details_list, messages = request.from_(carrier_gateway).parse()
88+
```
89+
90+
???+ check "Tracking output"
91+
92+
```python
93+
print(tracking_details_list)
94+
# [
95+
# TrackingDetails(
96+
# carrier_name="canadapost",
97+
# carrier_id="canadapost",
98+
# tracking_number="7023210039414604",
99+
# events=[
100+
# TrackingEvent(
101+
# date="2011-04-04",
102+
# description="Order information received by Canada Post",
103+
# location="",
104+
# code="INDUCTION",
105+
# time="13:34",
106+
# signatory="",
107+
# )
108+
# ],
109+
# delivered=None,
110+
# )
111+
# ]
112+
```

‎docs/guide/gateway.md‎

Lines changed: 0 additions & 45 deletions
This file was deleted.

‎docs/guide/gateways.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
## `Create`
2+
3+
The Gateway encapsulate the access to the carrier's API. A carrier gateway instance
4+
can created by using the `purplship.gateway` Gateway's initializer.
5+
6+
```python
7+
import purplship
8+
carrier_gateway = purplship.gateway["carrier_name"].create(...)
9+
```
10+
11+
### Carrier Gateways
12+
13+
=== "Plain"
14+
```python
15+
import purplship
16+
17+
# canadapost_gateway = purplship.gateway["carrier_name"].create(
18+
canadapost_gateway = purplship.gateway["canadapost"].create(
19+
{
20+
"username": "username",
21+
"password": "password",
22+
"customer_number": "123456789",
23+
"test": True
24+
}
25+
)
26+
```
27+
28+
=== "Typed"
29+
```python
30+
import purplship
31+
# from purplship.mappers.[carrier].settings import Settings
32+
from purplship.mappers.canadapost.settings import Settings
33+
34+
# canadapost_gateway = purplship.gateway["carrier_name"].create(
35+
canadapost_gateway = purplship.gateway["canadapost"].create(
36+
Settings(
37+
username="username",
38+
password="password",
39+
customer_number="123456789",
40+
test=True
41+
)
42+
)
43+
```
44+
45+
46+
47+
#### USPS Settings
48+
49+
| Name | Type | Description
50+
| --- | --- | --- |
51+
| `username` | `str` | **required**
52+
| `password` | `str` | **required**
53+
| `id` | `str` |
54+
| `test` | `bool` |
55+
| `carrier_id` | `str` |
56+
57+
58+
#### UPS Package Settings
59+
60+
| Name | Type | Description
61+
| --- | --- | --- |
62+
| `username` | `str` | **required**
63+
| `password` | `str` | **required**
64+
| `access_license_number` | `str` | **required**
65+
| `account_number` | `str` |
66+
| `id` | `str` |
67+
| `test` | `bool` |
68+
| `carrier_id` | `str` |
69+
70+
71+
#### Purolator Courier Settings
72+
73+
| Name | Type | Description
74+
| --- | --- | --- |
75+
| `username` | `str` | **required**
76+
| `password` | `str` | **required**
77+
| `account_number` | `str` | **required**
78+
| `user_token` | `str` |
79+
| `language` | `str` |
80+
| `id` | `str` |
81+
| `test` | `bool` |
82+
| `carrier_id` | `str` |
83+
84+
85+
#### FedEx Express Settings
86+
87+
| Name | Type | Description
88+
| --- | --- | --- |
89+
| `user_key` | `str` | **required**
90+
| `password` | `str` | **required**
91+
| `meter_number` | `str` | **required**
92+
| `account_number` | `str` | **required**
93+
| `id` | `str` |
94+
| `test` | `bool` |
95+
| `carrier_id` | `str` |
96+
97+
98+
#### Dicom Settings
99+
100+
| Name | Type | Description
101+
| --- | --- | --- |
102+
| `username` | `str` | **required**
103+
| `password` | `str` | **required**
104+
| `billing_account` | `str` |
105+
| `id` | `str` |
106+
| `test` | `bool` |
107+
| `carrier_id` | `str` |
108+
109+
110+
#### Canada Post Settings
111+
112+
| Name | Type | Description
113+
| --- | --- | --- |
114+
| `username` | `str` | **required**
115+
| `password` | `str` | **required**
116+
| `customer_number` | `str` | **required**
117+
| `contract_id` | `str` |
118+
| `language` | `str` |
119+
| `id` | `str` |
120+
| `test` | `bool` |
121+
| `carrier_id` | `str` |
122+
123+
124+
#### Canpar Settings
125+
126+
| Name | Type | Description
127+
| --- | --- | --- |
128+
| `username` | `str` | **required**
129+
| `password` | `str` | **required**
130+
| `id` | `str` |
131+
| `test` | `bool` |
132+
| `carrier_id` | `str` |
133+
134+
135+
#### BoxKnight Settings
136+
137+
| Name | Type | Description
138+
| --- | --- | --- |
139+
| `username` | `str` | **required**
140+
| `password` | `str` | **required**
141+
| `id` | `str` |
142+
| `test` | `bool` |
143+
| `carrier_id` | `str` |
144+
145+
146+
!!! note ""
147+
*Note that all carrier gateway defined bellow have these additional parameters*
148+
149+
| Name | Type | Description
150+
| --- | --- | --- |
151+
| `carrier_name` | `str` | default: carrier name (eg: canadapost, purolator...)
152+
| `id` | `str` |
153+
| `test` | `boolean` |
154+

0 commit comments

Comments
 (0)