@@ -136,9 +136,12 @@ Why?
136
136
~~~~
137
137
138
138
Downstream builds are frequently done in sandboxed environments that cannot
139
- access the Internet. Even if this is not the case, and assuming that you took
140
- sufficient care to properly authenticate downloads, using the Internet
141
- is discouraged for a number of reasons:
139
+ access the Internet. The package sources are unpacked into this environment,
140
+ and all the necessary dependencies are installed.
141
+
142
+ Even if this is not the case, and assuming that you took sufficient care to
143
+ properly authenticate downloads, using the Internet is discouraged for a number
144
+ of reasons:
142
145
143
146
- The Internet connection may be unstable (e.g. due to poor reception)
144
147
or suffer from temporary problems that could cause the process to fail
@@ -159,22 +162,31 @@ is discouraged for a number of reasons:
159
162
How?
160
163
~~~~
161
164
162
- Your source distribution should either include all the files needed
163
- for the package to build, or allow provisioning them externally. Ideally,
164
- it should not even attempt to access the Internet at all, unless explicitly
165
- requested to. If that is not possible to achieve, the next best thing
166
- is to provide an opt-out switch to disable all Internet access.
165
+ If the package is implementing any custom build *backend * actions that use
166
+ the Internet, for example by automatically downloading vendored dependencies
167
+ or fetching Git submodules, its source distribution should either include all
168
+ of these files or allow provisioning them externally, and the Internet must not
169
+ be used if the files are already present.
170
+
171
+ Note that this point does not apply to Python dependencies that are specified
172
+ in the package metadata, and are fetched during the build and installation
173
+ process by *frontends * (such as :ref: `build ` or :ref: `pip `). Downstreams use
174
+ frontends that use local provisioning for Python dependencies.
167
175
168
- When such a switch is used, the build process should fail if some
169
- of the required files are missing, rather than try to fetch them automatically.
170
- This could be done e.g. by checking whether a `` NO_NETWORK `` environment
171
- variable is set to a non-empty value. Please also remember that if you are
172
- fetching remote resources, you must * verify their authenticity * (usually against
173
- a hash), to protect against the file being substituted by a malicious party .
176
+ Ideally, custom build scripts should not even attempt to access the Internet
177
+ at all, unless explicitly requested to. If any resources are missing and need
178
+ to be fetched, they should ask the user for permission first. If that is not
179
+ feasible, the next best thing is to provide an opt-out switch to disable
180
+ all Internet access. This could be done e.g. by checking whether
181
+ a `` NO_NETWORK `` environment variable is set to a non-empty value .
174
182
175
183
Since downstreams frequently also run tests and build documentation, the above
176
184
should ideally extend to these processes as well.
177
185
186
+ Please also remember that if you are fetching remote resources, you absolutely
187
+ must *verify their authenticity * (usually against a hash), to protect against
188
+ the file being substituted by a malicious party.
189
+
178
190
179
191
.. _support-system-dependencies-in-builds :
180
192
0 commit comments