8.1. platformids.__init__¶
8.1.1. Module¶
The package ‘platformids’ provides canonical enumerations of bit encoded numeric platform IDs for the Python implementations CPython, IPython, IronPython, Jython, and PyPy.
The core module contains the basic data definitions and the function interfaces for the aquisition and conversion of platform parameters.
Sources: platformids/__init__.py
The inline doc-strings of the module are spared in order to support in any case a slim memory-print and fast load time without the requirement of global optimization flags. Instead the documentation is enhanced free from restrictions resulting from inline format requirements.
The contained classes provide special variants of dict in order to manage dynamic enumeration repositories. This also contains the creation of dynamic enumeration constants for short-term reporistory integration.
Due to the required support for a wide range of OS platforms including various Python implementations the collection classes are avoided.
8.1.2. Constants¶
8.1.2.1. Naming Conventions¶
The bitmasks arrays represent a record of a set of hierachical components. The hierrachy implies that a specific type is by definition a member of a specific upper class - similar to the inheritance hierachy of classes in object oriented designs. For example a distribution Fedora is also a member of the Linux type of OS, and therefore a member of the POSIX based OS category. Thus the numeric definition of RTE_FEDORA <dist> implies by default the bits for RTE_LINUX <ostype> and RTE_POSIX <category> also to be set.
The managed values are hereby represented in various input and output formats. Therefore the name of the appropriate function interfaces are based on a simple convention. The main representation is a bitmask vector representing a record with contained values shifted to the assigned bit position. The numeric values in general are defined as appropriate for simple bit operations without required shift operations. The conversion in some cases requires the content of the bitmask field, which is defined as the segment, where the value is defined by the bitmask relative to the field defined by the segment of the record.
Figure: Bitarray stack numbering definitions ¶
The the introduced names are used as part of the encoding and decoding interfaces as a hint to their input and output formats. The general definition of the names are:
- num:
For numeric values based on shifted 32bit values, where the complete upper hierarchy is contained. E.g. the category RTE_POSIX has the 32bit value 0x10000000, the distribution RTE_FEDORA has the 32bit value of dist 0x10810000:
RTE_FEDORA = 0x00010000 | RTE_LINUX RTE_FEDORA = 0x00010000 | 0x00800000 | RTE_POSIX RTE_FEDORA = 0x00010000 | 0x00800000 | 0x10000000 RTE_FEDORA = 0x10810000
- bits:
For numeric values based on shifted 32bit values, where the upper hierarchy is not contained. This could be easily evaluated from the 32bit value by using the pre defined bitmask RTE_DIST_B for the dist field.
RTE_FEDORA_B = RTE_FEDORA & RTE_DIST_B RTE_FEDORA_B = 0x10810000 & RTE_DIST_B RTE_FEDORA_B = 0x10810000 & 0x007f0000 RTE_FEDORA_B = 0x00010000
- segment:
A segment is a pure field value, where the numeric value is defined by the portion of bits relative to the field. E.g. RTE_POSIX has the numeric value 0x100000000, while it’s segment value of the category field is 0x1,
RTE_FEDORA_S = RTE_FEDORA_S & RTE_FEDORA_B >> 16 RTE_FEDORA_S = 0x00010000 >> 16 RTE_FEDORA_S = 0x1
- str:
The string representation of the appropriate field, which is in most cases the cumulated value of the hierarchical upper fields. This is because for the relative values no specific definitions exist, or better to say the represent a branch of attributes in a hierarchical graph. E.g. CentOS, or Solaris11 is in any case defined as a POSIX based OS, of type Linux or SunOS5.
RTE_FEDORA_STR = "Fedora"
8.1.2.2. Platform Definitions¶
The internal representation of the platform parameter is an int used as bit-array for binary logic operations - see also Bitmasks for Numeric Vectors. The most interfaces support the bit-array representation as well as the alternatively string name macros as defined by the sys.platform interface.
8.1.2.3. Structure of bit masks¶
The predefined bitmasks are provided as contant-variables of the form RTE_<name>,
RTE_RHEL7, RTE_CENTOS7, RTE_SOLARIS11, RTE_WIN2019S
which covers the grouping of bit-mask blocks and the increments within these groups. For example the value of CentOS7
val = (w, x, y, z) = RTE_CENTOS7
is represented by the corresponding bit encodings
val[0] = w -> <category> = RTE_POSIX val[1] = x -> <ostype> = RTE_LINUX val[2] = y -> <dist> = RTE_CENTOS val[3] = z -> <distrel> = RTE_CENTOS7
as defined by the following scheme
Figure: Standard Bit-Arrays - read more…¶
The general algorithm of the calculation for the bit-mask is based on the grouping of categories, type sets, and members into nested bit-blocks - <Bit Masks for OS and Distro Releases>. The combination of category bit masks for bit-blocks and the addition of sub-blocks for context-bitmasks of it’s members combines the performance of logical bit-operations with the reduction of the number of required bits. The principle is similar to the network addresses of TCP networks for routing. The lower bits are reserved for the groups and members of a category, which is similar to a class-X subnetwork address schemes. This is required due to the vast number of permutations of possible OS releases, which else would lead to bit arrays of astronomical dimensions.
8.1.2.4. Bit-Mask Definitions¶
The following additional definitions are introduced.
The bit-mask provides the bit for the OS as well as the bit for the base category and set - see OS Type and Distribution Categorization
For the details and complete numbering refer to the distribution modules OS Type and Distribution Categorization. The provided canonical details are - see commandline interface rtplatformids:
category = posix ostype = linux ostype-id = linux osrel-vers = [4, 16, 15] dist = fedora distrel = fedora-27.0.0 distrel-name = Twenty Seven distrel-key = fedora27 distrel-version = [27, 0, 0] distrel-hexversion = 285279488
Enum Values:
Base type blocks:
Sets of POSIX base system platformids:
RTE_BSD - bsd: BSD, - OpenBSD, FreeBSD, NetBSD - as Posix system [POSIX].
RTE_OSX - darwin: Darwin/OS-X, as Posix system [POSIX], no macpath-legacy.
RTE_DEBIAN - debian: debian - as Posix system [POSIX].
RTE_LINUX - linux: Linux with specific add-ons - OS, DIST, GNU - as Posix system [POSIX].
RTE_OSX - osx: Darwin/OS-X, as Posix system [POSIX], no macpath-legacy.
RTE_SOLARIS - solaris: UNIX/Solaris, as Posix system [POSIX].
.
RTE_GENERIC: Undefined platform for special cases.
Control Variables:
RTE: Current runtime-environment variable.
For the complete list refer to the sources [platformids.__init__.py].
8.1.2.5. Calculation of bit masks¶
A typical example for the base of the mapping and algorithms is:
# category: posix RTE_POSIX = 8192 #: Posix systems using fcntl [POSIX]. # set: OS-X # bit-block: Apple - OS-X RTE_OSX = RTE_POSIX + 1 #: Darwin/OS-X, as Posix system [POSIX], no macpath-legacy. RTE_OSX = RTE_POSIX + 2 #: Darwin/OS-X, as Posix system [POSIX], no macpath-legacy. # set: Sun - Solaris RTE_SOLARIS = RTE_POSIX + 16 #: UNIX/Solaris, as Posix system [POSIX]. # set: BSD RTE_BSD = RTE_POSIX + 32 #: BSD, - OpenBSD, FreeBSD, NetBSD - as Posix system [POSIX]. # set: Linux RTE_LINUX = RTE_POSIX + 64 #: Linux with specific add-ons - OS, DIST, GNU - as Posix system [POSIX]. # members" Linux RTE_CENTOS = RTE_LINUX + 1 #: CentOS RTE_CENTOS4 = RTE_LINUX + 2 #: CentOS-4 RTE_CENTOS5 = RTE_LINUX + 3 #: CentOS-5 RTE_CENTOS6 = RTE_LINUX + 4 #: CentOS-6 RTE_CENTOS7 = RTE_LINUX + 5 #: CentOS-7 RTE_FEDORA = RTE_LINUX + 32 #: Fedora RTE_FEDORA19 = RTE_LINUX + 33 #: Fedora-19 RTE_FEDORA27 = RTE_LINUX + 34 #: Fedora-27 RTE_DEBIAN = RTE_LINUX + 64 #: Debian RTE_DEBIAN6 = RTE_LINUX + 65 #: Debian - squeeze RTE_DEBIAN7 = RTE_LINUX + 66 #: Debian - wheezy RTE_DEBIAN8 = RTE_LINUX + 67 #: Debian - jessy RTE_DEBIAN9 = RTE_LINUX + 68 #: Debian - stretch
The calculations are for OS and distributions:
# # explicit # if RTE & RTE_POSIX: # use category pass if RTE & RTE_LINUX: # use set pass if RTE & RTE_CENTOS: # use distro pass if RTE & RTE_CENTOS7: # use release pass # # hierarchical # if RTE & RTE_POSIX: # use category if RTE & RTE_LINUX: # use set # do s.th. ... if RTE & RTE_CENTOS7: # use release pass else: # do s.th. ... elif RTE & RTE_BSD: # use set # do s.th. else... if RTE & RTE_OPENBSD: # use release pass else: # do s.th. else...
The calculations are for URI and schemes:
if RTE & RTE_URI: # use category pass if RTE & RTE_HTTP: # use scheme pass
8.1.2.6. Bitmask Conversions¶
The provided bitmask is encoded as a 32bit integer vector, where the segments contain the partial values. Due to the hierarch of the bit segments each value represents a hirarchical context. Thus the actual semantic of a bit-segment depends on it’s upper segment values. The partial values are therefore by default represented as the cumulated bitmask from the highest bit.
RTE_CATEGORY = 0xf0000000 #: bit: 31-28 RTE_OSTYPE = 0xffc00000 #: bit: 31-22 RTE_DIST = 0xfffff000 #: bit: 31-12 RTE_DISTREL = 0xffffffff #: bit: 31-0
These could be converted by simple bit-operations into the isolated sub-values by pre-defined bit-masks.
RTE_CATEGORY_B = 0xf0000000 #: bit: 31-28 RTE_OSTYPE_B = 0x0fc00000 #: bit: 27-22 RTE_DIST_B = 0x003ff000 #: bit: 21-12 RTE_DISTREL_B = 0x00000fff #: bit: 11-0
For example the value for Fedora sets specific bits for the segment dist, which has another semantics for the context of a Windows OS. Here for Fedora
RTE_FEDORA = RTE_POSIX & RTE_CATEGORY_B + RTE_LINUX & RTE_OSTYPE_B + RTE_FEDORA & RTE_DIST_B
The caller must be aware of the context in order to intepret the semantics. For example
fedora_bits = RTE_FEDORA & RTE_DIST_B winXY_bits = RTE_WINXY & RTE_DIST_B
could be equal when the context is omitted, even though the intentional semantics is forseen to be completely different:
fedora_bits = winXY_bits
The other aspect is the varying layout of the distrel field for specific versioning schemes. The applied versioning schemes are decided by the distributions, which even changes during the lifetime of some distributions, e.g. CentOS, Gentoo, and recently seemingly Windows from Window10 on. This even includes the combined variation of the dist and distrel fileds for versioning schemes with large value ranges. Thus the context within the hierarchy is critical for the interpretation and extraction of the subfields.
For simple reliable conversions refer to the provided functions of the API, or the specific intefraces provided by the appropriate distribution module.
8.1.2.7. Memory Management¶
The custom bit-mask blocks are managed by the assignment of reserved value ranges. These has to be handled cooperative by the application, no range checks for the assignment of net key/value/pairs is done.
The values are readonly once assigned. A basic protection is implemented, where a reassignment attempt raises an exception.
8.1.2.8. Application Hints¶
The bitmasks schould be used as numeric values where ever possible. The conversion shoudl be used for initial cases and code-segment decisions only, but avoided within repetitive loops.
8.1.2.9. Helper Constants¶
The helper support constant values to ease the calculations of the resulting values from bitmask records for casual application.
8.1.2.10. Bitmask Field¶
The bitmask field values extract the actual value of the selected field only.
RTE_CATEGORY_B = 0xf0000000 - bit: 31-28
RTE_OSTYPE_B = 0x0f800000 - bit: 27-23
RTE_DIST_B = 0x007f0000 - bit: 22-16
RTE_DISTREL_B = 0x0000ffff - bit: 15-0
For example by:
(RTE & RTE_CATEGORY_B) == RTE_POSIX (RTE & RTE_OSTYPE_B) == RTE_LINUX (RTE & RTE_DIST_B) == RTE_RHEL
8.1.2.11. Bit-Shift¶
The shift values represent the numeric value of the first bit after the applied shift operation.
RTE_CATEGORY_SHIFT = 28 - bit: 28
RTE_OSTYPE_SHIFT = 23 - bit: 23
RTE_DIST_SHIFT = 16 - bit: 16
RTE_DISTREL_SHIFT = 0 - bit: 0
For example:
((RTE_CENTOS & RTE_OSTYPE_B) >> RTE_OSTYPE_SHIFT) == 1 ((RTE_LINUX & RTE_OSTYPE_B) >> RTE_OSTYPE_SHIFT) == 1
8.1.2.12. Bit-Field Offset¶
The bit-field offsets provide the number of shifted bits for each bitmask-field.
RTE_CATEGORY_OFFSET = 0x0fffffff - bit: 28
RTE_OSTYPE_OFFSET = 0x007fffff - bit: 23
RTE_DIST_OFFSET = 0x0000ffff - bit: 16
RTE_DISTREL_OFFSET = 0x00000000 - bit: 0
For example:
(RTE_OSTYPE_OFFSET + 1) == (RTE_LINUX & RTE_OSTYPE_B)
8.1.2.13. Hirarchical Bit-Value¶
The hierarchical bit-values represent the resulting cumulated value of the bit-field whithin the tree hierarchy.
RTE_CATEGORY = 0xf0000000 - bit: 31-28
RTE_OSTYPE = 0xff800000 - bit: 31-23
RTE_DIST = 0xffff0000 - bit: 31-16
RTE_DISTREL = 0xffffffff - bit: 31-0
For example:
( (RTE_CENTOS & RTE_CATEGORY_B) | (RTE_CENTOS & RTE_OSTYPE_B ) | (RTE_CENTOS & RTE_DIST_B ) ) == RTE_CENTOS
8.1.3. Attributes¶
The following attributes are official interface and could be used alternively to the access functions.
8.1.3.1. RTE¶
The RTE variable is assigned during the initial load of the module. The value represents the current runtime platform as a bit mask with a mixed bit array and integer encoding to be used for bit and integer operations. The represented platforms, versions and releases are hierrachical and ordered, so greater and smaller, or equal comparison operators could be applied. For possible values refer to the constants ‘RTE_*’, see Platform Definitions.
8.1.3.2. rte2num¶
The map of string and for smart coding of the integer values too onto the defined numerical enum values.
rte2num = { <str-or-num>: RTE_<*>, } # application: rte2num['bsd'] == RTE_BSD rte2num[RTE_BSD] == RTE_BSD
For the complete list refer to the sources [platformids.__init__.py].
8.1.3.3. num2rte¶
The map of numerical values onto the defined string values.
num2rte = { RTE_<*>: <str-or-num>, } # application: rte2num[RTE_BSD] == 'bsd'
For the complete list refer to the sources [platformids.__init__.py].
8.1.3.4. custom_category¶
Manages the dynamic allocation of custom enumerations for the category. Is defined by the class ProtectedDictEnum, which provides in particular the method add_enum for the assignment of the next free number including the reservation for the rest of the lifetime of the current process.
8.1.3.5. custom_ostype¶
Manages the dynamic allocation of custom enumerations for the ostype. Is defined by the class ProtectedDictEnum, which provides in particular the method add_enum for the assignment of the next free number including the reservation for the rest of the lifetime of the current process.
8.1.3.6. custom_dist¶
Manages the dynamic allocation of custom enumerations for the dist. Is defined by the class ProtectedDictEnum, which provides in particular the method add_enum for the assignment of the next free number including the reservation for the rest of the lifetime of the current process.
8.1.4. Environment¶
8.1.4.1. PLATFORMIDS_ALTBASE¶
The environment variable PLATFORMIDS_ALTBASE defines an alternative base directory for the internal search by the pattern:
# try defaults modname, modfilepath = get_modlocation(‘mymodule’) if modfilepath == None: # try alternate by environ modname, modfilepath = get_modlocation(‘mymodule’, mbase=os.environ.get(‘PLATFORMIDS_ALTBASE’, None)
The value is checked after the standard path as defined either by default, or by hard-coded parameters. Thus it is for security reasons prohibited to replace any present standard module.
8.1.5. Platform Modules¶
The main module platformids implements the generic framework and configuration data for the major standard platforms. Additional platform data and eventually required functions are loaded during initialization. This includes custom modules for new platforms an releases provided by the application. Therefore a search for non-matched modules is performed, which in addition could be directed by the environment variable PLATFORMIDS_ALTBASE.
The search hierarchy including platform dependencies is defined by:
0. system data - prohibit redefinition of present system data
0.1 mbase_altbase = os.environ['CommonProgramFiles'] + os.sep + 'platformids'
0.2 mbase_altbase = os.sep + 'etc' + os.sep + 'platformids'
1. alternate data
1.1 mbase_altbase = os.getenv('PLATFORMIDS_ALTBASE', None)
2. user data
2.1 mbase_altbase = os.environ['LOCALAPPDATA'] + os.sep + 'platformids'
2.2 mbase_altbase = os.environ['HOME'] + os.sep + '.config' + os.sep + 'platformids'
2.3 mbase_altbase = os.environ['HOME'] + os.sep + 'platformids'
For additional details refer to get_modlocation.
8.1.6. Functions¶
The provided functions are grouped into categrories:
decode_*_to_*: decodes a given element to specified representation type
encode_*_to_32bit: encodes a given element into it’s 32bit bitmask representation as a hex-value
fetch_*: reads out the specified value from the current runtime environment
get_*: gets a value from the specified dict
set_*: sets a value of the specified dict
8.1.6.1. decode_rte_category_to_num¶
-
platformids.__init__.decode_rte_category_to_num(rte=276889600)[source]¶ Decodes the compressed category from the 32bit integer bitmask into the corresponding integer enum.
- Parameters
rte –
The comppressed runtime environment identifier bitmask.
default := RTE
- Returns
Integer value of the category enum.
- Raises
pass-through –
Examples:
decode_rte_category_to_num() => RTE_WPEMU # on windows emulator on posix => RTE_POSIX # on posix platforms => RTE_PWEMU # on posix on windows emulator - mainly Cygwin => RTE_WINDOWS # on windows platforms
8.1.6.2. decode_rte_dist_to_num¶
-
platformids.__init__.decode_rte_dist_to_num(rte=276889600)[source]¶ Decodes the compressed dist from the 32bit integer bitmask into the corresponding integer enum. Recognizes the ostype domain e.g. for RTE_NT.
- Parameters
rte –
The comppressed runtime environment identifier bitmask.
default := RTE
- Returns
Integer value of the dist enum.
- Raises
pass-through –
Examples:
decode_rte_dist_to_num() => RTE_DEBIAN # on Debian Linux => RTE_FEDORA # on Fedora Linux => RTE_NT # on Windows NT => RTE_OPENBSD # on OpenBSD => RTE_OSX # on newer apple osx platforms
Recognizes the distrel extension flag and the date based version flag.
decode_rte_dist_to_num() => RTE_ARCHLINUX # on Arch Linux => RTE_OPENWRT # on OpenWRT Linux
8.1.6.3. decode_rte_distrel_to_num¶
-
platformids.__init__.decode_rte_distrel_to_num(rte=276889600)[source]¶ Decodes the compressed distrel from the 32bit integer bitmask into the corresponding integer enum. Recognizes the ostype and dist domain, the distrel extension flag.
- Parameters
rte –
The comppressed runtime environment identifier bitmask.
default := RTE
- Returns
Integer value of the encoded distrel.
- Raises
pass-through –
- Examples:
decode_rte_distrel_to_num() => RTE_DEBIAN96 # on Debian-9.6 - Stretch => RTE_FEDORA29 # on Fedora-29 => RTE_OPENBSD63 # on OpenBSD-6.3 => RTE_OSX1068 # on Snowleopard / last update 10.6.8 => RTE_WIN2012R2 # on Windows2000R2 - dist = RTE_NT63 - distrel = 9600 Beginning with NT10_0 the version changes continously, thus no complete const: => RTE_NT100 + 1803 # on Windows10 Professional - dist = RTE_NT100 - distrel = 1803 => RTE_NT100 + 1809 # on Windows10 Professional - dist = RTE_NT100 - distrel = 1809
8.1.6.4. decode_rte_distrel_to_segments¶
-
platformids.__init__.decode_rte_distrel_to_segments(rte=276889600)[source]¶ Decodes the compressed distrel from the 32bit integer bitmask into the corresponding tuple of integer segments.
This is probably one of the most important functions, because it has the knowledge to split distrel including calling a custom-callback function when required. Recognizes the ostype and dist domain, the distrel extension flag in order to determine the further processing. The supported special cases of known and pre-loaded standard distributions are hardcoded for better performance here, currently these are:
ArchLinux, KaliLinux Windows-NT BlackArch, Gentoo, Armbian, ArchLinux, BlackArch, Gentoo, KaliLinux
- Parameters
rte –
The comppressed runtime environment identifier bitmask.
default := RTE
- Returns
Tuple of Integer values of the encoded segments, either as defined by the default layout, or any known as defined by additional extended and/or custom criteria.
- Raises
pass-through –
- Examples:
decode_rte_distrel_to_segments() => ret == (5, 50, 0) # on Armbian-5.50 - Stretch => ret == (7, 6, 0) # on CentOS-7.6-1804 => ret == (9, 6, 0) # on Debian-9.6 - Stretch => ret == (9, 6, 0) # on Raspbian-9.6 - Stretch => ret == (29, 0, 0) # on Fedora-29 => ret == (2019, 1, 0) # on KaliLinux-2019.01 => ret == (6, 3, 0) # on OpenBSD-6.3 => ret == (18, 6, 2) # on OpenWRT-18.6.2 => ret == (10, 6, 8) # on Snowleopard / last update 10.6.8 => ret == (2600, 0, 0) # on WindowsXP 32bit Professional => ret == (1809, 0, 0) # on Windows10 Professional version 1809 => ret == (1511, 0, 0) # on Windows10 IoT Core version 1511
8.1.6.5. decode_rte_ostype_to_num¶
-
platformids.__init__.decode_rte_ostype_to_num(rte=276889600)[source]¶ Decodes the compressed ostype from the 32bit integer bitmask into the corresponding integer enum.
- Parameters
rte –
The comppressed runtime environment identifier bitmask.
default := RTE
- Returns
Integer value of the ostype enum.
- Raises
pass-through –
Examples:
decode_rte_ostype_to_num() => RTE_BSD # on bsd platforms => RTE_DARWIN # on newer apple osx platforms => RTE_LINUX # on linux platforms => RTE_NT # on windows-nt platforms
8.1.6.6. decode_rte_to_segments¶
-
platformids.__init__.decode_rte_to_segments(rte=276889600)[source]¶ Decodes the compressed components from the 32bit integer bitmask into the corresponding segments of relative integer values.
- Parameters
rte –
The comppressed runtime environment identifier bitmask.
default := RTE
- Returns
Tuple of integer values of the components.
ret := => (#category-bits, #ostype-bits, #dist-bits, #distrel-bits)
Where the following os true:
rte == #category-bits << 28 | #ostype-bits << 23 | #dist-bits << 16 | #distrel-bits rte == encode_rte_segments_to_32bit(#category-bits, #ostype-bits, #dist-bits, #distrel-bits) rte == encode_rte_segments_to_32bit( *decode_rte_to_segments( rte ) )
- Raises
pass-through –
- Examples:
ret = decode_rte_to_tuple() => ret == (0x1, 0x2, 0x2, 0x1860) # on OpenBSD-6.3 => ret == (0x1, 0x4, 0x2, 0x28c8) # on Snowleopard / last update 10.6.8 => ret == (0x1, 0x1, 0x3, 0x24c0) # on Debian-9.6 - Stretch => ret == (0x1, 0x1, 0x1, 0x7400) # on Fedora-29 => ret == (0x1, 0x8, 0x2, 0x2260) # on Solaris-11.3 => ret == (0x2, 0x1, 0x50, 0x4563) # on Windows10 Professional - NT-10.0.17763
8.1.6.7. decode_rte_to_tuple¶
-
platformids.__init__.decode_rte_to_tuple(rte=276889600)[source]¶ Decodes the compressed components from the 32bit integer bitmask into the corresponding tuple of partial integer enums.
- Parameters
rte –
The comppressed runtime environment identifier bitmask.
default := RTE
- Returns
Tuple of integer values of the components.
ret := => (#category-num, #ostype-num, #dist-num, #distrel-num)
Where the following os true:
ret == #category-num | #ostype-num | #dist-num | #distrel-num ret == #category-num + #ostype-num + #dist-num + #distrel-num
- Raises
pass-through –
- Examples:
decode_rte_to_tuple() => (RTE_POSIX, RTE_BSD, RTE_OPENBSD, RTE_OPENBSD63) # on OpenBSD-6.3 => (RTE_POSIX, RTE_DARWIN, RTE_OSX, RTE_OSX1068) # on Snowleopard / last update 10.6.8 => (RTE_POSIX, RTE_LINUX, RTE_DEBIAN, RTE_DEBIAN96) # on Debian-9.6 - Stretch => (RTE_POSIX, RTE_LINUX, RTE_FEDORA, RTE_FEDORA29) # on Fedora-29 => (RTE_POSIX, RTE_UNIX, RTE_SOLARIS, RTE_SOLARIS11) # on Solaris11 => (RTE_WINDOWS, RTE_NT, RTE_NT100, RTE_WIN10) # on Windows10 Professional
8.1.6.8. decode_rte_to_tuple_str¶
-
platformids.__init__.decode_rte_to_tuple_str(rte=276889600)[source]¶ Decodes the compressed components from the 32bit integer bitmask into the corresponding tuple of string keywords.
- Parameters
rte –
The comppressed runtime environment identifier bitmask.
default := RTE
- Returns
Tuple of keywords of string values for the components.
ret := => (<category>, <ostype>, <dist>, <distrel>)
- Raises
pass-through –
- Examples:
decode_rte_to_tuple_str() => ('posix', 'bsd', 'openbsd', 'openbsd63') # on OpenBSD-6.3 => ('posix', 'darwin', 'osx', 'osx1068') # on Snowleopard / last update 10.6.8 => ('posix', 'linux', 'debian', 'debian96') # on Debian-9.6 - Stretch => ('posix', 'linux', 'fedora', 'fedora29') # on Fedora-29 => ('posix', 'unix', 'solaris', 'solaris11') # on Solaris11 => ('windows', 'nt', 'nt100', 'win10p') # on Windows10 Professional
8.1.6.9. decode_version_str_to_segments¶
-
platformids.__init__.decode_version_str_to_segments(v)[source]¶ Split a version string separated by ‘.’ into an integer array.
decode_version_str_to_segments('1.22.17') => (1, 22, 17) decode_version_str_to_segments('2012.02.17') => (2012, 2, 17) decode_version_str_to_segments('10.0.1809') => (10, 0, 1809)
A tiny utility - frequently required.
- Parameters
v –
Version string with maximal 3 digits:
('1.2.3') => (1, 2, 3) ('1.2') => (1, 2, 0) ('1') => (1, 0, 0)
- Returns
Tuple of int.
('1.2.3') => (1, 2, 3) ('1.2') => (1, 2, 0) ('1') => (1, 0, 0)
In case an error occured:
(0, 0, 0)
- Raises
None. –
8.1.6.10. encode_rte_to_32bit¶
-
platformids.__init__.encode_rte_to_32bit(**kargs)[source]¶ Encodes the provided 32bit bitmask of each field into the combined integer value of the bitmask vector.
- Parameters
kargs –
- category:
The numeric 32bit bitmask of the category:
category := ( <int-enum> | <category-key> ) int-enum: the integer enum, preferbly a predefined value-by-var category-key: the key value as string to be evaluated by one of:: *rte2num*: the common mapping dictionary *get_rte2num*: the function interface for *rte2num*
default is 0
- ostype:
The numeric 32bit bitmask of the ostype:
ostype := ( <int-enum> | <ostype-key> ) int-enum: the integer enum, preferbly a predefined value-by-var ostype-key: the key value as string to be evaluated by one
of:
*rte2num*: the common mapping dictionary *get_rte2num*: the function interface for *rte2num*
default is 0.
- dist:
The numeric 32bit bitmask of the dist:
ostype := ( <int-enum> | <dist-key> ) int-enum: the integer enum, preferbly a predefined value-by-var dist-key: the key value as string to be evaluated by one
of:
*rte2num*: the common mapping dictionary *get_rte2num*: the function interface for *rte2num*
default is 0.
- distrel:
The numeric 32bit encoded integer for the distrel, default is 0.
- Returns
The 32bit compressed bitmask of the RTE.
- Raises
pass-through –
8.1.6.11. encode_rte_segments_to_32bit¶
-
platformids.__init__.encode_rte_segments_to_32bit(**kargs)[source]¶ Converts the numeric base values of the fields into a 32bit bitmask and encodes them into the combined integer value of the bitmask vector.
- Parameters
kargs –
- category:
The non-shifted base value of the category:
category := ( <int-val> ) int-val: the relative integer value of the category bits
default is 0
- ostype:
The non-shifted base value of the ostype:
ostype := ( <int-val> ) int-val: the relative integer value of the ostype bits
default is 0.
- dist:
The non-shifted base value of the dist:
dist := ( <int-val> ) int-val: the relative integer value of the dist bits
default is 0.
- distrel:
The non-shifted encoded base value of the distrel, default is 0.
- Returns
The 32bit compressed bitmask of the RTE.
- Raises
pass-through –
8.1.6.12. fetch_category¶
8.1.6.13. fetch_dist¶
-
platformids.__init__.fetch_dist()[source]¶ Scans the platform and returns the numeric id for the current dist.
- Parameters
none –
- Returns
Returns the dist as integer enum. The bitmask includes the category and ostype.
res = <category-bits><ostype-bits><dist-bits><distrel-bits-zero>
- Raises
Examples:
fetch_ostype() => RTE_DEBIAN => RTE_FEDORA => RTE_CENTOS => RTE_OPENBSD => RTE_SOLARIS
8.1.6.14. fetch_dist_tuple¶
-
platformids.__init__.fetch_dist_tuple()[source]¶ Scans the platform and returns the complete tuple for the current dist.
- Parameters
none –
- Returns
Returns the complete tuple of information related to a distribution.
res = (<distid-string>, <distrel-string>, <distrel-tuple>, <ditst-rel-key-string>)
- Raises
Examples:
fetch_dist_tuple() => ('sunos', '5.10.0' , (5, 10, 0, int(_p)), 'sunos5100') => ('sunos', '5.11.3' , (5, 11, 3), 'sunos5113') => ('fedora', '27.0.0' , (27, 0, 0), 'fedora27') => ('centos', '7.6.0' , (7, 6, 0), 'centos76') => ('debian', '9.4.0' , (9, 4, 0), 'debian94')
8.1.6.15. fetch_ostype¶
-
platformids.__init__.fetch_ostype()[source]¶ Scans the platform and returns the numeric id for the current ostype.
- Parameters
none –
- Returns
Returns the ostype as integer enum. The bitmask includes the category.
res = <category-bits><ostype-bits><dist-bits-zero><distrel-bits-zero>
- Raises
Examples:
fetch_ostype() => RTE_BSD => RTE_CYWINNT => RTE_DARWIN => RTE_LINUX => RTE_NT => RTE_UNIX
8.1.6.16. fetch_platform_distribution¶
-
platformids.__init__.fetch_platform_distribution()[source]¶ Scans the platform and returns the complete distribution data prepared for common post-processing.
- Parameters
none –
- Returns
Returns the information about the current distribution.
result := ( <lowercase-dist-id>, # 0: lower case str including release number <dist-release-number-str>, # 1: the release number as string <original-literal-release-name>, # 2: case sensitive release name <original-literal-dist-name>, # 3: case sensitive distribution name <dist-release-number-list>, # 4: release version as list of int <lowercase-dist->, # 5: lower case str of dist name only )
- Raises
For the supported standard platforms see Supported Standard OS and Dists.
Examples:
public distribution
category
ostype
dist
distrel
product-type
returned tuple
Cywin
pwemu
cygwinnt
cygwin
2.6.8
–
(‘cywin268’, ‘2.6.8’, ‘Cygwin-2.6.8’, ‘Cygwin’, (2, 6, 8), ‘cywin’)
Fedora27
posix
linux
fedora
27
–
(‘fedora27’, ‘27’, ‘Fedora-27’, ‘Fedora’, (27, 0, 0), ‘fedora’)
OS-X HighSierra
posix
darwin
osx
17.6.0
–
(‘osx1760’, ‘17.6.0’, ‘OSX-17.6.0’, ‘Snowleopard’, (17, 6, 0), ‘osx’)
OS-X Snowleopard
posix
darwin
osx
10.8.0
–
(‘osx1068’, ‘10.6.8’, ‘OSX-10.6.8’, ‘Snowleopard’, (10, 8, 0), ‘osx’)
Solaris10
posix
unix
solaris
10
–
(‘solaris10’, ‘10.0’, ‘Solaris-10’, ‘Solaris’, (10, 0, 0), ‘solaris’)
Solaris11
posix
unix
solaris
11.3
–
(‘solaris11’, ‘11.3.0’, ‘Solaris-11.3’, ‘Solaris’, (5, 11, 3), ‘solaris’)
Windows Server 2016
windows
nt
nt100
10.0.1809
server
(‘nt100’, ‘10.0.1809’, ‘NT-10.0.1809’, ‘NT’, (10, 0, 1809),’nt’)
Windows Server 2019 Essentials
windows
nt
nt100
10.0.1809
server
(‘nt100’, ‘10.0.1809’, ‘NT-10.0.1809’, ‘NT’, (10, 0, 1809),’nt’)
Windows10 Home
windows
nt
nt100
10.0.1809
home
(‘nt100’, ‘10.0.1809’, ‘NT-10.0.1809’, ‘NT’, (10, 0, 1809),’nt’)
Windows10 Professional
windows
nt
nt100
10.0.1809
workstation
(‘nt100’, ‘10.0.1809’, ‘NT-10.0.1809’, ‘NT’, (10, 0, 1809),’nt’)
8.1.6.17. fetch_platform_distribution_num¶
-
platformids.__init__.fetch_platform_distribution_num()[source]¶ The numeric version of ‘fetch_platform_distribution’.
- Parameters
none –
- Returns
Returns the information about the current distribution.
result := ( #dist, # 0: distribution identifier #distrel, # 1: distribution release identifier #dist-release-number-list>, # 2: release version as list of int )
- Raises
Examples:
public distribution
category
ostype
dist
distrel
product-type
returned tuple
Cywin
pwemu
cygwinnt
cygwin
2.6.8
–
(RTE_CYGWIN, #CYGWIN268, (2, 6, 8))
Fedora27
posix
linux
fedora
27
–
(RTE_FEDORA, #FEDORA27, (27, 0, 0))
OS-X Snowleopard
posix
darwin
osx
17.6.0
–
(RTE_OSX, #OSX1068, (10, 6, 0))
Solaris10
posix
unix
solaris
10
–
(RTE_SOLARIS, #SOLARIS100, (10, 0, 0))
Solaris11
posix
unix
solaris
11.3
–
(RTE_SOLARIS, #SOLARIS113, (11, 3, 0))
Windows Server 2016
windows
nt
nt100
10.0.1809
server
(RTE_NT100, #NT1001809, (10, 0, 1809)
Windows10 Professional
windows
nt
nt100
10.0.1809
workstation
(RTE_NT100, #NT1001809, (10, 0, 1809)
8.1.6.18. fetch_platform_os¶
-
platformids.__init__.fetch_platform_os()[source]¶ Scans the platform and returns the information on the OS including the name and the release version.
The name of the OS is commonly basically the kernel name. The ostype of linux has one common kernel only, while OS in the bsd and unix family commonly have distribution specific customized kernels.
- Parameters
none –
- Returns
Returns the information about the current os.
res = ( <lowercase-os-id>, # osname: lower case str of os name <os-release-number-str>, # osrel: string of os release version <os-release-number-list>, # osrel: list of int of os release version <lowercase-os-rel-id>, # osname+osrel: lower case str rel + id )
- Raises
Examples:
public distribution
category
ostype
osname
osrel
product-type
returned tuple
Cywin
pwemu
cygwinnt
cygwin
2.6.8
–
(‘cywin’, ‘2.6.8’, (2, 6, 8), ‘cywin268’)
Fedora27
posix
linux
linux
4.17.14
–
(‘linux’, ‘4.17.14’, (4, 17, 14), ‘linux41714’)
OS-X HighSierra
posix
darwin
darwin
17.6.0
–
(‘darwin’, ‘17.6.0’, (17, 6, 0), ‘darwin1760’)
OS-X Snowleopard
posix
darwin
darwin
10.8.0
–
(‘darwin’, ‘10.8.0’, (10, 8, 0),’darwin1080’)
Solaris10 (1)
posix
unix
sunos
5.10.0
–
(‘sunos’, ‘5.10.0’, (5, 10, 0, <patch>), ‘sunos5100’)
Solaris11
posix
unix
sunos
5.11.3
–
(‘sunos’, ‘5.11.3’, (5, 11, 3), ‘sunos5113’)
Windows Server 2016
windows
nt
nt100
10.0.1809
server
(‘nt’, ‘10.0.1809’, (10, 0, 1809), ‘nt1001809’)
Windows Server 2019 Essentials
windows
nt
nt100
10.0.1809
server
(‘nt’, ‘10.0.1809’, (10, 0, 1809), ‘nt1001809’)
Windows10 Home
windows
nt
nt100
10.0.1809
home
(‘nt’, ‘10.0.1809’, (10, 0, 1809), ‘nt1001809’)
Windows10 Professional
windows
nt
nt100
10.0.1809
workstation
(‘nt’, ‘10.0.1809’, (10, 0, 1809), ‘nt1001809’)
- (1): Solaris10
The supported OS Solaris10 is here treated special, though it returns the combined kernel patch level as part of it’s release version. For example:
('SunOS', 'solaris10', '5.10', 'Generic_147148-26', 'i86pc', 'i386') # for the architecture refer to [machineids] ^^^^^^^^^^^^^^^^^results in the optional non-standard enty dist[2][3]:
('sunos', '5.10.0', (5, 10, 0, 14714826), 'sunos5100') ^^^^^^^^Anyhow, due to the nearby coming EOL of Solaris10, the patch-level is ignored by the numeric calculations. Thus treated as additional optional information to be used when required.
The major members of the OS family of the BSD type OS’s are numbered slightly different. While the Solaris distibution and operating system numbering is already related, the major BSD operating systems do not distinguish the release numbering between the distribution and the operating system. These are actually derived from BSD-4.x releases, an have even anchestor relationships to each other these could meanwhile could be treated as autonomous operating systems with common anchestors. This is also dur to the partially compatible, but independent kernels which are bound to specific distributions and releases. Thus the numbers of OS and distributions are treated identical by the platformids.
Some Examples:
public distribution
category
ostype
osname
osrel
product-type
returned tuple
DragonFlyBSD
posix
bsd
dragonflybsd
5.4.0
–
(‘dragonflybsd’, ‘5.4.0’, (5, 4, 0), ‘dragonflybsd540’)
FreeBSD
posix
bsd
freebsd
11.2
–
(‘freebsd’, ‘11.2’, (11, 2, 0), ‘freebsd112’)
NetBSD
posix
bsd
netbsd
8.0
–
(‘netbsd’, ‘8.0’, (8, 0, 0), ‘netbsd80’)
OpenBSD
posix
bsd
openbsd
6.4
–
(‘openbsd’, ‘6.4’, (6, 4, 0), ‘openbsd64’)
8.1.6.19. fetch_platform_os_num¶
-
platformids.__init__.fetch_platform_os_num()[source]¶ The numeric version of ‘fetch_platform_os’.
- Parameters
none –
- Returns
Returns the information about the current os.
res = ( <enum-os-id>, # osname: lower case str of os name <32bit-os-release-number>, # osrel: string of os release version <os-release-number-list>, # osrel: list of int of os release version <enum-os-rel-id>, # osname+osrel: lower case str rel + id )
- Raises
8.1.6.20. fetch_rte_hexversion¶
-
platformids.__init__.fetch_rte_hexversion()[source]¶ Retrieves the bitmask encoding for current runtime environemnt.
- Parameters
None. –
- Returns
The encoded bitmask to be used for caching and RTE.
- Raises
pass-through –
The Resolution Algorithm
The resolution of the numeric distribution IDs is based on the enumeration of the contained parts. This is finally based on the arbitrary assignment of specific integer numbers to specific distributions. These are dynamically maintained in the data structure platformids.rte2num. Each known distribution and release requires an entry in this dictionary. The values consist of a core-set and additional sets whch are loaded dynamically.
The function fetch_rte_hexversion is the main encryption point for the gathered data from the actual platform in order to read out the corresponding bitmask.
The handling of the bulk of releases is designed by either a literal match of an existing key, or the incremental search by iteration of the release version components.
For example the ditribution Debian may have defined a mapping debian9, while the actual release has the version 9.6. Or for example CentOS a mapping for CentOS-7, missing the release 7.6. The resolution algoritm first tries to find a mapping for the key
distrelkey = debian96
when missing the next trial is
distrelkey = debian9
which is one of the major core defintions. Thus the default setup will match
distrelkey = ret2num['debian9']
or by the function interface
distrelkey = get_ret2num('debian9')
The returned components of the hexvalue on Debian-9.6 without a specific map for the release 9.6, but for 9 or 9.0 are:
platformids.decode_rte_to_tuple_str(RTE) => ('posix', 'linux', 'debian', 'debian9')
The complete algorithm tries the additional resolution steps for the hierarchical sub identifiers, when the Debian definitions are for example completely missing.
0. literal distrelkey 1. reduced distrelkey 2. distname 3. ostype 4. category
8.1.6.21. get_modlocation¶
-
platformids.__init__.get_modlocation(mname, mbase=None, mpaths=None, **kargs)[source]¶ Calls the pythonids.get_modulelocation function with specific default parameters for the platformids.
- Parameters
mbase –
Base for module search paths by default within the subdirectory of platformids. The filepath name with a trailing separator.
default := os.path.dirname(__file__) + os.sep
The base path is used within the post-processing of the eventually matched path, thus has to be appropriate for each item of mpaths.
mname –
The relative path of the module in dotted Python notation.
mname := ( <dotted-module-name-str> | <dotted-module-name-path-name-str> )
mpaths –
List of module specific search paths for platformids, these are relative to mbase,
default := [ 'dist', 'custom', 'net', 'embed', '', ]
resulting in:
default := [ mbase + 'dist' + os.sep, mbase + 'custom' + os.sep, mbase + 'net' + os.sep, mbase + 'embed' + os.sep, mbase, ]
kargs –
- permitrel:
Permit the return of relative module names within mpath. If False absolute only, which is relative to an existing sys.path entry.
permitrel := ( True, # returns a relative module name if within subtree False # returns in any case a module name relative to sys.path )
Sets relative base within platformids as the default:
rbase = os.path.normpath(os.path.dirname(__file__)) + os.sep
- Returns
Returns in case of a match the resulting entry within sys.modules:
match -> (<relative-module-name>, <module-file-path-name>,)
The default when no match occured is to rely on the more versatile search mechanism of the import implementation of the concrete Python implementation for another final trial by the caller:
default -> (<mname>, None,)
- Raises
PlatformIDsError – ‘mbase’ does not match ‘mpaths’
PlatformIDsPresentError – missing ‘mbase’
pass-through –
8.1.6.22. get_num2rte¶
8.1.6.23. get_rte2num¶
-
platformids.__init__.get_rte2num(rte)[source]¶ Gets corresponding numerical representation for the numeric or string value.
Alternatively the official dict rte2num could be used.
- Parameters
rte – Numeric enum value or string representation of the requested platform.
- Returns
The numeric value, or None*.
- Raises
None –
8.1.7. ProtectedDict¶
-
class
platformids.__init__.ProtectedDict(*args, **kargs)[source]¶ Implements a ‘dict’ with protection against modification of items. This is in order to protect a repository from erroneous modifications of it’s entries by malicious code. The deletion is still supported, which is considered as intentional, thus done beeing aware of the consequences.
The main intention for the platformids is to avoid inconsistencies of hard-coded values of assigned enumerations by runtime redefinitions. Unintentional redefinitions also may proof as hard to debug.
The member attribute self.strict_check controls how new items are added:
- single new item:
add silently
- single item which is already present:
strict_check == True: raises exception
strict_check == False: ignores silently
- set of items, where none of the new set is present:
add silently
- set of items, where at least one is present:
strict_check == True: raises exception
strict_check == False: add silently new, ignore present silently
The common variables such as central dictionaries are thus read-only protected during the runtime of the process. The response style for the attempt to alter a value could be modified - raised to a stronger level - by the attribute ‘strict_check’, which raises an exception once set.
8.1.7.1. __init__¶
-
ProtectedDict.__init__(*args, **kargs)[source]¶ - Parameters
args –
to dict (pass-through) –
kargs –
non-defined are passed-through to dict
- int_keys_only:
Controls type of valid keys.
int_keys_only := ( True # permits interger keys only | False # permits any valid *dict* key )
- strict_check:
Defines the handling of values for present keys.
True: when True raises exception for present items, False: silently ignores new values for present items
- Returns
Initialized object, or raises exception.
- Raises
pass-through –
8.1.7.2. __setattr__¶
-
ProtectedDict.__setattr__(name, value)[source]¶ Filters and controls attribute values to be set.
- Parameters
name –
Sets the attribute named by name. Establishes special handling for the in-band control attributes.
- strict_check:
The value can only be raised to True in order to strengthen the strictness.
- strict_check_reset:
If the value is set to True, than the member attribute ‘strict_check’ is set to False.
Else calls ‘dict.__setattr__’.
value – The value is passed through to dict, see also for special values of name.
- Returns
Either filters defined control attributes - see name, or calls dict.__setattr__.
- Raises
pass-through –
8.1.7.3. __setitem__¶
-
ProtectedDict.__setitem__(key, value)[source]¶ Filter for already present mappings controlled by the member strict_check.
- Parameters
name –
Sets the item named by name. Controlled by the attribute strict_check.
self.strict_check := ( True # permits only creation of non-present | False # normal behaviour )
Dependent on the presence raises an exception when strict is enabled.
value – The value is passed through to dict, see also for special values of name.
- Returns
dict.__setitem__
- Raises
PlatformIDsPresentError – Conditional based on strict_check, if True raises for present attributes PlatformIDsPresentError.
PlatformIDsKeyError – For non-int keys when int_keys_only is set.
pass-through –
8.1.7.4. update¶
-
ProtectedDict.update(dict2, *args, **kargs)[source]¶ Adds a set of items, filters each for presence.
- none of the new set is present:
adds all silently
- at least one is present:
strict_check == True: raises exception
strict_check == False: add silently
- Parameters
dict2 –
Adds items controlled by the attribute strict_check.
self.strict_check := ( True # permits only creation of non-present | False # normal behaviour )
Dependent on the presence of at least one raises an exception when strict is enabled.
args – Passed to dict.update.
kargs – Passed to dict.update.
- Returns
dict.update or None
- Raises
PlatformIDsPresentError – Conditional based on strict_check, if True raises for present attributes PlatformIDsPresentError.
PlatformIDsKeyError – For non-int keys when int_keys_only is set.
pass-through –
8.1.8. ProtectedDictEnum¶
-
class
platformids.__init__.ProtectedDictEnum(**kargs)[source]¶ Implements the dynamic creation and management of numeric enumeration values. These are used as dynamic assigned constants with the life time of the process itself. The enums are optimized to be used in conjunction with numeric bitmask vectors. The values are created on-demand, e.g. for dynamic loaded packages, and could be removed when no longer required. Thus are released than for the reuse.
The management of the unused numeric values for assignment is performed by two levels.
The value is managed by a protected counter within the defined range.
Once the values are exhausted, the dictionary is used as release map. This is required due to the possible storage of the values by the application, thus assigned values cannot be reassigned and though the ranges could become used sparse.
This level is much slower, though it is based on the lookup and remove form the unused-map. And of course, previous releases has to be present
.
Anyhow, e.g. in case of platformids for the ostype and dist the ranges for the additional dynamic assigments in are about 100 for the distribution dist, about 25 for the OS type ostype, and about 12 for the category category. This should be in practical realworld use-cases more than sufficient.
REMARK: Implemented as dict for coming extensions.
8.1.8.1. __init__¶
-
ProtectedDictEnum.__init__(**kargs)[source]¶ Initializes key reservation. The custom range values has to comply to the bitmask segments. These define the minimal and maximal values in accordance to the common ranges by the mathematical notation:
values := [custom_min, custom_max) # excluding custom_max
The values could be processed by the application of the helper constants, see Helper Constants. E.g. in case of dist for the ostype context of RTE_LINUX :
custom_min == ((RTE_LINUX + RTE_DISTEXT + RTE_DIST_OFFSET + 0) & RTE_DIST_B) custom_max == ((RTE_LINUX + RTE_DISTEXT + RTE_DIST_OFFSET + 126) & RTE_DIST_B)
or
(custom_min >> 16) == 0 (custom_max >> 16) == 126
The caller is responsible for the appropriate values.
- Parameters
kargs –
default pass-through to dict
- custom_max:
Defines the maximum of custom range. When missing no custom range os available.
custom_max > custom_min
default := None
- custom_min:
Defines the minimum of custom range. When missing no custom range os available.
default := None
- custom_offset:
Defines the offset for the increment and decrement. This is required e.g. in case of bitmask fields with segments starts at bits greater than 0.
default := 0
- Returns
Initialized object, or raises exception.
- Raises
PlatformIDsEnumerationError – Erroneous custom range is provided.
pass-through –
8.1.8.2. __delattr__¶
8.1.8.3. __delitem__¶
8.1.8.4. __setattr__¶
-
ProtectedDictEnum.__setattr__(name, value)[source]¶ Protects the enumeration management attributes from non-managed direct access.
- Parameters
name –
Excludes reserved attributes from direct access.
name :=( 'reserved' | 'custom_min' | 'custom_max' )
value – Value to be set.
- Returns
None
- Raises
pass-through –
8.1.8.5. __setitem__¶
8.1.8.6. add_enum¶
-
ProtectedDictEnum.add_enum(value=True)[source]¶ Reserves and assigns the next free unique key to the value. The assigned key value is returned for use. Custom ranges are available when the values custom_max and custom_min are initialized appropriately.
- Parameters
None. –
- Returns
Either returns the reserved key, or raises exception when range is exhausted.
- Raises
PlatformIDsCustomError – No custom ranges are configured.
PlatformIDsEnumerationError – The configured range is exhausted.
pass-through –
8.1.8.7. check_next_free_enum¶
-
ProtectedDictEnum.check_next_free_enum()[source]¶ Checks and returns the next free value.
Does not reserve, just displays next.
- Parameters
None –
- Returns
Value to be used by next call of add_enum.
- Raises
PlatformIDsCustomError – No custom ranges are configured.
PlatformIDsEnumerationError – Range exhausted, no free values are available.
8.1.8.8. delete_enum¶
-
ProtectedDictEnum.delete_enum(enum)[source]¶ Releases a given enum, either continous values by changing the reserved values, or by adding a non-continous values to the dict of released items. The non-continous released items could be cleared by the method purge.
- Parameters
enum – Enum key.
- Returns
None.
- Raises
pass-through –
8.1.8.9. purge¶
-
ProtectedDictEnum.purge(**kargs)[source]¶ Clears the list of deleted non-continous enums. Deletes all entries in the release map, which could be added incremental and continous to the reserved-list of vallues beginning at from custom_min. This re-initializes for the purged items the pure numeric first level assignement by ranges - spares for these the lookup in the non-continous list.
- Parameters
kargs –
- maxrel:
Maximum to be released.
- minrel:
Minimum to be released.
- Returns
Returns the number of actual releases.
- Raises
PlatformIDsEnumerationError – Could not fulfil minrel.
pass-through –
8.1.8.10. update¶
-
ProtectedDictEnum.update(dict2, *args, **kargs)[source]¶ Prohibits updates. This is required in order to avoid arbitrary updates which simply would complicate the management and assignment of further values. Thus only individual values could be added and removed.
- Parameters
None. –
- Returns
Raises Exception.
- Raises
