Skip to content

Commit 18e522e

Browse files
jobselkojobselko
committed
Update user docs
1 parent b090afa commit 18e522e

File tree

5 files changed

+175
-112
lines changed

5 files changed

+175
-112
lines changed

‎docs/user/guides/_SUMMARY.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
* [Setup your own PyPI](pypi.md)
1+
* [Set up your own PyPI](pypi.md)
22
* [Sync from Remote Repositories](sync.md)
33
* [Upload and Manage Content](upload.md)
44
* [Publish and Host Python Content](publish.md)

‎docs/user/guides/publish.md

Lines changed: 34 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -24,18 +24,20 @@ Distribution before it is consumable).
2424

2525
```
2626
{
27-
"pulp_href": "/pulp/api/v3/publications/python/pypi/cad6007d-7172-41d1-8c22-0ec95e1d242a/",
28-
"pulp_created": "2021-03-09T04:30:16.686784Z",
29-
"repository_version": "/pulp/api/v3/repositories/python/python/8fbb24ee-dc91-44f4-a6ee-beec60aa542d/versions/1/",
30-
"repository": "/pulp/api/v3/repositories/python/python/8fbb24ee-dc91-44f4-a6ee-beec60aa542d/",
27+
"pulp_href": "/pulp/api/v3/publications/python/pypi/0196ba31-cd04-7aba-a7b4-71a98a976745/",
28+
"prn": "prn:python.pythonpublication:0196ba31-cd04-7aba-a7b4-71a98a976745",
29+
"pulp_created": "2025-05-10T12:35:48.103758Z",
30+
"pulp_last_updated": "2025-05-10T12:35:48.205361Z",
31+
"repository_version": "/pulp/api/v3/repositories/python/python/0196ba30-e15e-71ea-9867-33aeceb5a87e/versions/1/",
32+
"repository": "/pulp/api/v3/repositories/python/python/0196ba30-e15e-71ea-9867-33aeceb5a87e/",
3133
"distributions": []
3234
}
3335
```
3436

3537
## Host a Publication (Create a Distribution)
3638

3739
To host a publication, (which makes it consumable by `pip`), users create a distribution which
38-
will serve the associated publication at `/pypi/<distribution.base_path>/`
40+
will serve the associated publication at `${BASE_ADDR}/pypi/${DIST_BASE_PATH}/`.
3941

4042
=== "Run"
4143

@@ -49,15 +51,22 @@ will serve the associated publication at `/pypi/<distribution.base_path>/`
4951

5052
```
5153
{
52-
"pulp_href": "/pulp/api/v3/distributions/python/pypi/4839c056-6f2b-46b9-ac5f-88eb8a7739a5/",
53-
"pulp_created": "2021-03-09T04:36:48.289737Z",
54-
"base_path": "foo",
55-
"base_url": "/pypi/foo/",
56-
"content_guard": null,
57-
"pulp_labels": {},
58-
"name": "foo",
59-
"publication": "/pulp/api/v3/publications/python/pypi/a09111b1-6bce-43ac-aed7-2e8441c22704/"
60-
}
54+
"pulp_href": "/pulp/api/v3/distributions/python/pypi/0196ba32-0be6-7f85-bbb3-cf561a4e2d88/",
55+
"prn": "prn:python.pythondistribution:0196ba32-0be6-7f85-bbb3-cf561a4e2d88",
56+
"pulp_created": "2025-05-10T12:36:04.200189Z",
57+
"pulp_last_updated": "2025-05-10T12:36:04.200232Z",
58+
"base_path": "foo",
59+
"base_url": "http://localhost:5001/pypi/foo/",
60+
"content_guard": null,
61+
"no_content_change_since": "2025-05-10T12:36:04.200232Z",
62+
"hidden": false,
63+
"pulp_labels": {},
64+
"name": "foo",
65+
"repository": null,
66+
"publication": "/pulp/api/v3/publications/python/pypi/0196ba31-cd04-7aba-a7b4-71a98a976745/",
67+
"allow_uploads": true,
68+
"remote": null
69+
}
6170
```
6271

6372
## Automate Publication and Distribution
@@ -68,7 +77,7 @@ updated automatically when new repository versions are created.
6877
```bash
6978
# This configures the repository to produce new publications when a new version is created
7079
pulp python repository update --name foo --autopublish
71-
# This configures the distribution to be track the latest repository version for a given repository
80+
# This configures the distribution to track the latest repository version for a given repository
7281
pulp python distribution update --name foo --repository foo
7382
```
7483

@@ -77,7 +86,7 @@ pulp python distribution update --name foo --repository foo
7786
Functionality may not work or may be incomplete. Also, backwards compatibility when upgrading
7887
is not guaranteed.
7988

80-
## Enable Pull-Through Caching:
89+
## Enable Pull-Through Caching
8190

8291
Only packages present in your repository will be available from your index, but adding a remote source to
8392
your distribution will enable the pull-through cache feature. This feature allows you to install any package
@@ -101,28 +110,26 @@ pulp python distribution update --name foo --remote bar
101110
The metadata and packages can now be retrieved from the distribution:
102111

103112
```bash
104-
$ http $BASE_ADDR/pypi/foo/simple/
105-
$ http $BASE_ADDR/pypi/foo/simple/shelf-reader/
113+
http "${BASE_ADDR}/pypi/foo/simple/"
114+
http "${BASE_ADDR}/pypi/foo/simple/shelf-reader/"
106115
```
107116

108117
!!! note
109118
When domains are enabled, it is necessary to include the domain name within the URL, like so:
110-
`$BASE_ADDR/pypi/${DOMAIN_NAME}/foo/simple/`
119+
`${BASE_ADDR}/pypi/${DOMAIN_NAME}/foo/simple/`
111120

112121
The content is also pip installable:
113122

114123
```bash
115-
$ pip install --trusted-host localhost -i $BASE_ADDR/pypi/foo/simple/ shelf-reader
124+
pip install --trusted-host localhost -i "${BASE_ADDR}/pypi/foo/simple/" shelf-reader
116125
```
117126

118-
If you don't want to specify the distribution path every time, you can modify your `pip.conf`
119-
file. See the [pip docs](https://pip.pypa.io/en/stable/user_guide/#configuration) for more
120-
detail.:
127+
If you don't want to specify the distribution path every time, you can modify your `pip.conf` file:
121128

122129
=== "Run"
123130

124131
```bash
125-
$ cat pip.conf
132+
cat pip.conf
126133
```
127134

128135
=== "Output"
@@ -135,5 +142,7 @@ detail.:
135142
The above configuration informs `pip` to install from `pulp`:
136143

137144
```bash
138-
$ pip install --trusted-host localhost shelf-reader
145+
pip install --trusted-host localhost shelf-reader
139146
```
147+
148+
See the [pip docs](https://pip.pypa.io/en/stable/topics/configuration) for more details.

‎docs/user/guides/pypi.md

Lines changed: 35 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1-
# Setup your own PyPI:
1+
# Set up your own PyPI
22

3-
This section guides you through the quickest way to setup `pulp_python` to act as your very own
3+
This section guides you through the quickest way to set up `pulp_python` to act as your very own
44
private `PyPI`.
55

6-
## Create a Repository:
6+
## Create a Repository
77

88
Repositories are the base objects `Pulp` uses to store and organize its content. They are automatically
99
versioned when content is added or deleted and allow for easy rollbacks to previous versions.
@@ -19,20 +19,22 @@ versioned when content is added or deleted and allow for easy rollbacks to previ
1919

2020
```
2121
{
22-
"pulp_href": "/pulp/api/v3/repositories/python/python/3fe0d204-217f-4250-8177-c83b30751fca/",
23-
"pulp_created": "2021-06-02T14:54:53.387054Z",
24-
"versions_href": "/pulp/api/v3/repositories/python/python/3fe0d204-217f-4250-8177-c83b30751fca/versions/",
25-
"pulp_labels": {},
26-
"latest_version_href": "/pulp/api/v3/repositories/python/python/3fe0d204-217f-4250-8177-c83b30751fca/versions/1/",
27-
"name": "foo",
28-
"description": null,
29-
"retained_versions": null,
30-
"remote": null,
31-
"autopublish": false
32-
}
22+
"pulp_href": "/pulp/api/v3/repositories/python/python/0196ba29-52b9-7cf4-b12e-f3247f0eb3dc/",
23+
"prn": "prn:python.pythonrepository:0196ba29-52b9-7cf4-b12e-f3247f0eb3dc",
24+
"pulp_created": "2025-05-10T12:26:32.506906Z",
25+
"pulp_last_updated": "2025-05-10T12:26:32.517333Z",
26+
"versions_href": "/pulp/api/v3/repositories/python/python/0196ba29-52b9-7cf4-b12e-f3247f0eb3dc/versions/",
27+
"pulp_labels": {},
28+
"latest_version_href": "/pulp/api/v3/repositories/python/python/0196ba29-52b9-7cf4-b12e-f3247f0eb3dc/versions/0/",
29+
"name": "foo",
30+
"description": null,
31+
"retain_repo_versions": null,
32+
"remote": null,
33+
"autopublish": false
34+
}
3335
```
3436

35-
## Create a Distribution:
37+
## Create a Distribution
3638

3739
Distributions serve the content stored in repositories so that it can be used by tools like `pip`.
3840

@@ -46,35 +48,43 @@ Distributions serve the content stored in repositories so that it can be used by
4648

4749
```
4850
{
49-
"pulp_href": "/pulp/api/v3/distributions/python/pypi/e8438593-fd40-4654-8577-65398833c331/",
50-
"pulp_created": "2021-06-03T20:04:18.233230Z",
51+
"pulp_href": "/pulp/api/v3/distributions/python/pypi/0196ba29-8f95-776b-a782-78d7838f3f9f/",
52+
"prn": "prn:python.pythondistribution:0196ba29-8f95-776b-a782-78d7838f3f9f",
53+
"pulp_created": "2025-05-10T12:26:48.086775Z",
54+
"pulp_last_updated": "2025-05-10T12:26:48.086806Z",
5155
"base_path": "my-pypi",
52-
"base_url": "https://pulp3-source-fedora33.localhost.example.com/pypi/foo/",
56+
"base_url": "http://localhost:5001/pypi/my-pypi/",
5357
"content_guard": null,
58+
"no_content_change_since": null,
59+
"hidden": false,
5460
"pulp_labels": {},
5561
"name": "my-pypi",
56-
"repository": "/pulp/api/v3/repositories/python/python/3fe0d204-217f-4250-8177-c83b30751fca/",
62+
"repository": "/pulp/api/v3/repositories/python/python/0196ba29-52b9-7cf4-b12e-f3247f0eb3dc/",
5763
"publication": null,
58-
"allow_uploads": true
64+
"allow_uploads": true,
65+
"remote": null
5966
}
6067
```
6168

62-
## Upload and Install Packages:
69+
## Upload and Install Packages
6370

6471
Packages can now be uploaded to the index using your favorite Python tool. The index url will be available
65-
at `/pypi/<distribution.base_path>/simple/`.
72+
at `${BASE_ADDR}/pypi/${DIST_BASE_PATH}/simple/`.
6673

6774
```bash
75+
BASE_ADDR="http://localhost:5001"
76+
PLUGIN_SOURCE="shelf-reader"
77+
git clone https://github.com/asmacdo/shelf-reader.git
6878
# Build custom package
69-
python -m build $PLUGIN_SOURCE
79+
python -m build "$PLUGIN_SOURCE"
7080
# Upload built package distributions to my-pypi
71-
twine upload --repository-url $BASE_ADDR/pypi/my-pypi/simple/ -u admin -p password "$PLUGIN_SOURCE"dist/*
81+
twine upload --repository-url "${BASE_ADDR}/pypi/my-pypi/simple/" -u admin -p password "${PLUGIN_SOURCE}/dist/"*
7282
```
7383

7484
Packages can then be installed using your favorite Python tool:
7585

7686
```bash
77-
pip install --trusted-host localhost -i $BASE_ADDR/pypi/my-pypi/simple/ shelf-reader
87+
pip install --trusted-host localhost -i "${BASE_ADDR}/pypi/my-pypi/simple/" "$PLUGIN_SOURCE"
7888
```
7989

8090
Now you have a fully operational Python package index. Check out the other workflows to see more features of

‎docs/user/guides/sync.md

Lines changed: 58 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,6 @@
33
Users can populate their repositories with content from an external source like PyPI by syncing
44
their repository.
55

6-
76
## Create a Repository
87

98
=== "Run"
@@ -17,21 +16,23 @@ their repository.
1716

1817
```
1918
{
20-
"pulp_href": "/pulp/api/v3/repositories/python/python/8fbb24ee-dc91-44f4-a6ee-beec60aa542d/",
21-
"pulp_created": "2021-03-09T04:11:54.347921Z",
22-
"versions_href": "/pulp/api/v3/repositories/python/python/8fbb24ee-dc91-44f4-a6ee-beec60aa542d/versions/",
23-
"pulp_labels": {},
24-
"latest_version_href": "/pulp/api/v3/repositories/python/python/8fbb24ee-dc91-44f4-a6ee-beec60aa542d/versions/0/",
25-
"name": "foo",
26-
"description": null,
27-
"remote": null
28-
}
19+
"pulp_href": "/pulp/api/v3/repositories/python/python/0196ba2a-f353-736a-854c-2d415389a509/",
20+
"prn": "prn:python.pythonrepository:0196ba2a-f353-736a-854c-2d415389a509",
21+
"pulp_created": "2025-05-10T12:28:19.156941Z",
22+
"pulp_last_updated": "2025-05-10T12:28:19.169190Z",
23+
"versions_href": "/pulp/api/v3/repositories/python/python/0196ba2a-f353-736a-854c-2d415389a509/versions/",
24+
"pulp_labels": {},
25+
"latest_version_href": "/pulp/api/v3/repositories/python/python/0196ba2a-f353-736a-854c-2d415389a509/versions/0/",
26+
"name": "foo",
27+
"description": null,
28+
"retain_repo_versions": null,
29+
"remote": null,
30+
"autopublish": false
31+
}
2932
```
3033

3134
Reference: [Python Repository Usage](site:pulp_python/restapi/#tag/Repositories:-Python)
3235

33-
34-
3536
## Create a Remote
3637

3738
Creating a remote object informs Pulp about an external content source. In this case, we will be
@@ -49,29 +50,56 @@ itself, a fixture, or even an instance of Pulp 2.
4950

5051
```
5152
{
52-
"pulp_href": "/pulp/api/v3/remotes/python/python/a9bb3a02-c7d2-4b2e-9b66-050a6c9b7cb3/",
53-
"pulp_created": "2021-03-09T04:14:02.646835Z",
53+
"pulp_href": "/pulp/api/v3/remotes/python/python/0196ba2b-1461-7d0d-99f6-5f75610abf71/",
54+
"prn": "prn:python.pythonremote:0196ba2b-1461-7d0d-99f6-5f75610abf71",
55+
"pulp_created": "2025-05-10T12:28:27.617672Z",
56+
"pulp_last_updated": "2025-05-10T12:28:27.617697Z",
5457
"name": "bar",
5558
"url": "https://pypi.org/",
5659
"ca_cert": null,
5760
"client_cert": null,
5861
"tls_validation": true,
5962
"proxy_url": null,
6063
"pulp_labels": {},
61-
"pulp_last_updated": "2021-03-09T04:14:02.646845Z",
62-
"download_concurrency": 10,
64+
"download_concurrency": null,
65+
"max_retries": null,
6366
"policy": "on_demand",
6467
"total_timeout": null,
6568
"connect_timeout": null,
6669
"sock_connect_timeout": null,
6770
"sock_read_timeout": null,
6871
"headers": null,
6972
"rate_limit": null,
73+
"hidden_fields": [
74+
{
75+
"name": "client_key",
76+
"is_set": false
77+
},
78+
{
79+
"name": "proxy_username",
80+
"is_set": false
81+
},
82+
{
83+
"name": "proxy_password",
84+
"is_set": false
85+
},
86+
{
87+
"name": "username",
88+
"is_set": false
89+
},
90+
{
91+
"name": "password",
92+
"is_set": false
93+
}
94+
],
7095
"includes": [
7196
"shelf-reader"
7297
],
7398
"excludes": [],
7499
"prereleases": true,
100+
"package_types": [],
101+
"keep_latest_packages": 0,
102+
"exclude_platforms": []
75103
}
76104
```
77105

@@ -80,7 +108,7 @@ Reference: [Python Remote Usage](site:pulp_python/restapi/#tag/Remotes:-Python)
80108
## A More Complex Remote
81109

82110
If only the name of a project is specified, every distribution of every version of that project
83-
will be synced. You can use the version_specifier field to ensure only distributions you care
111+
will be synced. You can use the version specifier field to ensure only distributions you care
84112
about will be synced:
85113

86114
```bash
@@ -115,22 +143,22 @@ You can also filter packages by their type, platform and amount synced through t
115143
"exclude_platforms", and "keep_latest_packages" fields respectively, like so:
116144

117145
```bash
146+
# Sync only sdist and bdist_wheel package types, exclude any packages built
147+
# for windows and keep the five latest versions
118148
pulp python remote create \
119149
--name 'complex-filters' \
120150
--url 'https://pypi.org/' \
121151
--includes '["django"]' \
122-
--package-types '["sdist", "bdist-wheel"]' # only sync sdist and bdist-wheel package types \
123-
--exclude-platforms '["windows"]' # exclude any packages built for windows \
124-
--keep-latest-packages 5 # keep the five latest versions
152+
--package-types '["sdist", "bdist_wheel"]' \
153+
--exclude-platforms '["windows"]' \
154+
--keep-latest-packages 5
125155
```
126156

127157
Reference: [Python Remote Usage](site:pulp_python/restapi/#tag/Remotes:-Python)
128158

129-
130-
131159
### Creating a remote to sync all of PyPI
132160

133-
A remote can be setup to sync all of PyPI by not specifying any included packages like so:
161+
A remote can be set up to sync all of PyPI by not specifying any included packages, like so:
134162

135163
```bash
136164
pulp python remote create \
@@ -173,22 +201,25 @@ sync with. You are telling pulp to fetch content from the remote and add to the
173201

174202
```
175203
{
176-
"pulp_href": "/pulp/api/v3/repositories/python/python/8fbb24ee-dc91-44f4-a6ee-beec60aa542d/versions/1/",
177-
"pulp_created": "2021-03-09T04:20:21.896132Z",
204+
"pulp_href": "/pulp/api/v3/repositories/python/python/0196ba2a-f353-736a-854c-2d415389a509/versions/1/",
205+
"prn": "prn:core.repositoryversion:0196ba2b-655c-7745-b10f-bdde15a941c6",
206+
"pulp_created": "2025-05-10T12:28:48.349938Z",
207+
"pulp_last_updated": "2025-05-10T12:28:49.031497Z",
178208
"number": 1,
209+
"repository": "/pulp/api/v3/repositories/python/python/0196ba2a-f353-736a-854c-2d415389a509/",
179210
"base_version": null,
180211
"content_summary": {
181212
"added": {
182213
"python.python": {
183214
"count": 2,
184-
"href": "/pulp/api/v3/content/python/packages/?repository_version_added=/pulp/api/v3/repositories/python/python/8fbb24ee-dc91-44f4-a6ee-beec60aa542d/versions/1/"
215+
"href": "/pulp/api/v3/content/python/packages/?repository_version_added=/pulp/api/v3/repositories/python/python/0196ba2a-f353-736a-854c-2d415389a509/versions/1/"
185216
}
186217
},
187218
"removed": {},
188219
"present": {
189220
"python.python": {
190221
"count": 2,
191-
"href": "/pulp/api/v3/content/python/packages/?repository_version=/pulp/api/v3/repositories/python/python/8fbb24ee-dc91-44f4-a6ee-beec60aa542d/versions/1/"
222+
"href": "/pulp/api/v3/content/python/packages/?repository_version=/pulp/api/v3/repositories/python/python/0196ba2a-f353-736a-854c-2d415389a509/versions/1/"
192223
}
193224
}
194225
}

0 commit comments

Comments
 (0)