Top-Level Sections

This chapter discusses how you can access and manipulate top-level sections in a Pipfile and Pipfile.lock through a loaded model.

Sections as Properties

The Pipfile specification defines a set of standard fields a Pipfile may contain. Those sections are available for access with the dot notation (property access):

>>> for script in pipfile.scripts:
...     print(script)
...
build
changelog
docs
draft
release
tests

Most property names map directly to the section names defined in the specification, with dashes replaced by underscored:

>>> for package in pipfile.dev_packages:
...     print(package)
invoke
parver
towncrier
twine
wheel
pytest
pytest-xdist
pytest-cov
sphinx
sphinx-rtd-theme

For ergonomic concerns, some sections have aliases so they have more Pythonic names:

>>> for source in pipfile.sources:
...     print(source['url'])
...
https://pypi.org/simple
>>> for key in lockfile.meta:
...     print(key)
...
hash
pipfile-spec
requires
sources

Tip

The canonical names are still available as properties, so you can use pipfile.source and lockfile._meta if you want to.

The section properties are all writable, so you can use them to manipulate contents in of the Pipfile (or Pipfile.lock, although not recommended):

>>> pipfile.requires = {'python_version': '3.7'}
>>> pipfile.requires.python_version
'3.7'

Key-Value Access

The Pipfile specification allows arbitrary sections. Those sections are available with the bracket (key-value) syntax. Standard dict methods such as get() are also available:

>>> pipfile.get('pipenv', {}).get('allow_prereleases', False)
False

Note

The bracket syntax is also available for standard sections. They are only available in their canonical forms, however, not in normalized forms or aliases, so you will need to use keys like pipfile['dev-packages'], lockfile['_meta'], etc.

Missing Sections

The Pipfile specification allows any top-level sections to be missing. Plette does not attempt to normalize most them, and will raise KeyError or AttributeError if you access a missing key, to distinguish them from blank sections. You need to catch them manually, or use convenience dict methods (e.g. get()).

One exception to this rule is the source section in Pipfile. The specification explicitly states there will be a default source, and Plette reflects this by automatically adding one if the loaded Pipfile does not contain any sources. This means that the source section will always be present and not empty when you load it.

The automatically generated source contains the following data

name = "pypi"
url = "https://pypi.org/simple"
verify_ssl = true

Warning

You can delete either the automatically generated source, or the source section itself from the model after it is loaded. Plette assumes you know what you’re doing.