verschemes module
This module can be used to manage and enforce rules for version numbering.
The type used for fields with no type explicitly specified.
alias of int
Bases: verschemes._SegmentField
The definition of an atomic portion of a version segment value.
This is an immutable set of metadata defining the parameters of a field in a SegmentDefinition.
The attributes can be set only in the constructor by name or position and can be accessed by attribute name (preferred) or item index:
type (default: int) is the underlying type of the field value.
name (default: “value”) is the name of the field, which must be unique among all of the fields in a segment.
Each segment will often have only one field, so the name is defaulted to something quite generic, but it must be explicitly set to ensure uniqueness when the SegmentDefinition contains multiple fields.
If the field name is specified, it must be a valid Python identifier that does not start with an underscore. This field can then be identified by this name in the segment value of a Version subclass if the corresponding segment definition contains multiple fields, because the value is a subclass of namedtuple named Segment that has fields corresponding to the segment definition’s fields.
re_pattern (default: “[0-9]+”) is the regular expression pattern that the string representation of the field value must match.
render (default: str) is the function that takes the underlying value and returns its appropriate string representation. Note that in Python 2 this str is from the future package and is similar to unicode.
The default SegmentField instance.
The separator used for segments with no separator explicitly specified.
Bases: verschemes._SegmentDefinition
The definition of a version segment.
This is an immutable set of metadata defining the parameters of a segment.
The attributes can be set only in the constructor by name or position and can be accessed by attribute name (preferred) or item index:
optional (default: False) indicates whether the segment may be excluded from rendering and whether its value is allowed to be unspecified even if the segment has no default.
default (default: None) is the implied value of the segment when the value is unspecified (or None).
separator (default: ”.”) is the string within the version’s string representation that comes just before the segment value(s).
This value is ignored for the first segment in a version and also not rendered when all optional segments before it are unspecified.
fields (default: a singular SegmentField instance) is the sequence of metadata (SegmentField instances) for the field(s) in the segment.
name (default: None) is an optional name for the segment.
If the segment name is specified, it must be a valid Python identifier that does not start with an underscore. This segment can then be identified by this name in the Version subclass in which it is used:
separator_re_pattern (default: None) is an optional regular expression pattern that matches all allowed input separators.
If it is set, then a string representation given to the Version subclass constructor will allow any input matching this regular expression as the separator for this segment, but the separator attribute is the normal form used when rendering the version.
If it is not set, then the separator attribute is the only acceptable literal input form in addition to being the normal form.
This value is ignored for the first segment in a version.
The regular expression pattern for the segment’s possible string representations.
This is generated from the re_patterns of its field(s).
Whether a value for this segment is required.
It is required if it is not optional and has no default value.
Validate the given value and return the value as the inner type.
The given value may be:
The result will be:
The default SegmentDefinition instance.
Bases: builtins.tuple
A class whose instances adhere to the version scheme it defines.
The versioning rules are defined in SEGMENT_DEFINITIONS, which may be overridden in a subclass to make it more specific to the version scheme represented by the subclass.
The concept is that the class represents a particular set of versioning rules (i.e., a version scheme), and the instances of that class are version identifiers that follow those rules.
Pass the constructor either a version identifier as a str or the individual segment values in order corresponding to the SEGMENT_DEFINITIONS defined by the class (or any number of integers if using the default implementation). Optional segments and segments with default values may be passed a value of None or excluded from the end.
As of version 1.1, keyword arguments may also be given to the constructor when the keywords match the segments’ names. Any keyword arguments for segments also specified positionally will override the positional arguments.
The instance’s segment values can be accessed via standard indexing, slicing, and keys. For example, instance[0] returns the value of the instance’s first segment, instance[3:5] returns a tuple containing the values of the instance’s fourth and fifth segments, and since version 1.1 instance['name'] returns the value of the segment with name ‘name’.
As of version 1.1, individual segment values can also be accessed via properties if the segment was given a name and the name does not conflict with an existing attribute of the class.
The segment values acquired from indexing, slicing, keywords, and properties are cooked according to the segment definition (basically returning the default if the raw value is None). The raw values can be accessed with get_raw_item().
The parameters for segments in this version.
This can only be set as a class attribute and is validated/captured during class creation, after which it can be read as an attribute of the class. It cannot be modified within an existing class. It cannot be accessed directly from an instance.
If not using the default, this must be set to an iterable of SegmentDefinitions, one element for each segment, at least one of which must be non-optional.
The default (empty sequence) is special in that it allows for a variable and logically infinite number of segments, each following the rules of the default SegmentDefinition. This means that the default implementation supports the most common version scheme of an arbitrary number of integer segments separated by dots.
Return the raw segment value (or values if item is a slice).
This is an alternative to __getitem__() (i.e., bracket item retrieval) and named-segment properties, which cook the value(s) according to their segment definition(s).
Render the version into a string representation of normal form.
Pass False (or equivalent) for the exclude_defaults argument to stop the default behavior of excluding optional segments that have a default value but have not been explicitly set.
If there was only one way to render a version, then this method would not exist, and its implementation would be in __str__. There is, however, only one default way, which is done when __str__ is called, and that is to call this method with its default arguments.
There could be many ways to render a version, depending on its complexity and features. The base class implements rendering with only one simple argument (exclude_defaults) and two complex arguments (include_callbacks and exclude_callbacks). The two complex arguments (i.e., callback arguments) allow for future versions and subclasses to provide additional simple arguments. (Keep reading if this interests you.)
The signature of this method should be considered the most volatile in the project. The callback arguments should never be passed by position to keep the code prepared for injection of additional simple arguments in the base implementation that are more likely to be passed by position.
Callback structure
The callback arguments are sequences of metadata describing how the simple arguments are processed. The metadata may just be a function or a sequence consisting of a function and any additional arguments. Each callback function requires the ‘version’ (or ‘self’ if its a method) argument and the ‘index’ argument. The “additional” arguments mentioned above follow the required arguments in the callback function’s signature.
Callback processing
The functions in include_callbacks can return True (or equivalent) to force the segment identified by the ‘index’ argument to be included in the rendering. If no “include” callbacks force the inclusion of the segment, then the functions in exclude_callbacks can return True (or equivalent) to exclude the segment of the version identified by the ‘index’ argument in the rendering. Any segment with a value (i.e., not None) that is not excluded by this process will be rendered in the result. The exclude_defaults argument is an example of a simple argument whose affect is implemented via exclude_callbacks with the _render_exclude_defaults_callback method.
Return a copy of this version with the given segments replaced.
Each keyword argument can either be an underscore (‘_’) followed by the numeric segment index or the segment name. Each identified segment is replaced with the argument’s value. Segment name arguments take precedence over underscore-index arguments.
verschemes.python module
The Python verschemes module implements standard Python versioning.
Bases: verschemes.Version
A major Python version.
This version scheme has one segment that identifies the major Python version, which is only incremented for really major changes in the language. It is the base for the more detailed Python version classes and is mostly only useful itself for comparison. For example:
>>> python2 = PythonMajorVersion(2)
>>> my_python_version = PythonVersion('2.7.1')
>>> assert(my_python_version.major_version == python2)
Return a new PythonMajorVersion with the object’s values.
This is mainly useful in subclasses.
The ‘major’ segment value.
Bases: verschemes.python.PythonMajorVersion
A minor Python version.
This version scheme has two segments that identify the minor Python version, which is incremented for less earth-shattering changes in the language than a major version increment. It is the base for the more detailed Python version classes and is mostly only useful itself for comparison. For example:
>>> python33 = PythonMinorVersion(3, 3)
>>> my_python_version = PythonVersion(3, 4, 2)
>>> assert(my_python_version.minor_version > python33)
Return a new PythonMinorVersion with the object’s values.
This is mainly useful in subclasses.
The ‘minor’ segment value.
Bases: verschemes.python.PythonMinorVersion
A micro Python version.
This version scheme has three segments that identify the micro Python version, which is incremented for each bugfix release (see PEP 6). It is the base for the more detailed Python version classes and is mostly only useful itself for comparison. For example:
>>> python301 = PythonMicroVersion(3, 0, 1)
>>> my_python_version = PythonVersion(3, 0, 1, ('b', 1))
>>> assert(my_python_version.micro_version == python301)
Return a new PythonMicroVersion with the object’s values.
This is mainly useful in subclasses.
The ‘micro’ segment value.
Bases: verschemes.python.PythonMicroVersion
A complete, specific Python version.
This version scheme has four segments that identify a specific version of Python. See the link in the module documentation for details about the Python version scheme.
Whether this version represents a non-development release.
This simply says whether it is equivalent to its micro_version; that is, whether the SUFFIX-index value is None.
>>> assert(PythonVersion('3.4.1').is_nondevelopment)
>>> assert(not PythonVersion('3.4.1c1').is_nondevelopment)
>>> assert(not PythonVersion('3.4.1+').is_nondevelopment)
Whether this version represents a release.
This simply says whether the SUFFIX-index value is not ‘+’. A ‘+’ indicates that it is an unreleased version, built directly from the Subversion trunk; anything else is a release (be it development or non-development).
>>> assert(PythonVersion('3.4.1').is_release)
>>> assert(PythonVersion('3.4.1c1').is_release)
>>> assert(not PythonVersion('3.4.1+').is_release)
The ‘suffix’ segment value.
verschemes.pep440 module
The PEP 440 verschemes module implements standard PEP 440 public versioning. PEP 440 local versions are not supported by this module; they are just public versions with a hyphen and a numeric version (as implemented by the defaults in the base verschemes.Version class) appended.
This implementation is limited to six release-number segments, which should handle any reasonable scheme.
Bases: verschemes.Version
A PEP 440 public version.
The version scheme has an optional epoch segment followed by up to six release-number segments (named ‘releaseX’, where X is 1-6) followed by the optional pre_release, post_release, and development segments.
SEGMENT_DEFINITIONS contains the following named segments in order:
epoch: optional=True, default=0
release1: default=0, separator=’!’
release2: optional=True, default=0
release3: optional=True, default=0
release4: optional=True, default=0
release5: optional=True, default=0
release6: optional=True, default=0
field ‘serial’: type=int_empty_zero, re_pattern=’[0-9]*’
Whether this version represents a final release.
Return True if all of the ‘pre_release’, ‘post_release’, and ‘development’ segments have no value.
Override to provide the min_release_segments option.
The ‘development’ segment value.
The ‘epoch’ segment value.
The ‘post_release’ segment value.
The ‘pre_release’ segment value.
The ‘release1’ segment value.
The ‘release2’ segment value.
The ‘release3’ segment value.
The ‘release4’ segment value.
The ‘release5’ segment value.
The ‘release6’ segment value.
verschemes.postgresql module
The PostgreSQL verschemes module implements standard PostgreSQL versioning.
Bases: verschemes.Version
A major PostgreSQL version.
This version scheme has two segments that identify the major PostgreSQL version, which includes new features and requires a dump/reload of the database or use of the pg_upgrade module. It is the base for the more detailed PostgreSQL version classes and is mostly only useful itself for comparison. For example:
>>> pg83 = PgMajorVersion(8.3)
>>> my_version = PgVersion('8.3.4')
>>> assert(my_version.major_version == pg83)
Return a new PgMajorVersion with the object’s values.
This is mainly useful in subclasses.
The ‘major1’ segment value.
The ‘major2’ segment value.
Bases: verschemes.postgresql.PgMajorVersion
A complete, specific PostgreSQL version.
This version scheme has three segments that identify a specific release of PostgreSQL.
The ‘minor’ segment value.
verschemes.xorg module
The X.org verschemes module implements the standard X.org version number scheme.
An added rule is to extend the patch number’s pre-full-release value (99) to the minor number as well when preparing for a [major].0 full release.