5.1. pythonids.__init__

The package ‘pythonids’ provides the canonical core enumerations of bit encoded numeric IDs for the Python syntax.

5.1.1. Module

pythonids provides common information about the Python syntax.

Sources: pythonids/__init__.py

5.1.2. Constants

5.1.2.1. Syntax Releases - PYV{x}[{y}[{z}

Definitions of predefined values for the version of the Python syntax. Some typical feature-milestone values are provided as runtime constants for comparison operations as the resulting value from encode_pysyntax_to_16bit(). See PYVxyz.

PYV2   = 16384  # encode_pysyntax_to_16bit(2, 0, 0)
PYV26  = 17920  # encode_pysyntax_to_16bit(2, 6, 0)  - Python2.6
PYV27  = 18176  # encode_pysyntax_to_16bit(2, 7, 0)  - Python2.7
PYV3   = 24576  # encode_pysyntax_to_16bit(3, 0, 0)
PYV32  = 25088  # encode_pysyntax_to_16bit(3, 2, 0)  - Python3.2
PYV33  = 25089  # encode_pysyntax_to_16bit(3, 3, 0)  - Python3.3
PYV34  = 25600  # encode_pysyntax_to_16bit(3, 4, 0)  - Python3.4
PYV35  = 25856  # encode_pysyntax_to_16bit(3, 5, 0)  - Python3.5
PYV36  = 26112  # encode_pysyntax_to_16bit(3, 6, 0)  - Python3.6
PYV362 = 26114  # encode_pysyntax_to_16bit(3, 6, 2)
PYV365 = 26117  # encode_pysyntax_to_16bit(3, 6, 5)
PYV366 = 26118  # encode_pysyntax_to_16bit(3, 6, 6)
PYV37  = 26368  # encode_pysyntax_to_16bit(3, 7, 0)  - Python3.7
PYV371 = 26369  # encode_pysyntax_to_16bit(3, 7, 1)
PYV372 = 26370  # encode_pysyntax_to_16bit(3, 7, 2)
PYV373 = 26371  # encode_pysyntax_to_16bit(3, 7, 3)
PYV374 = 26372  # encode_pysyntax_to_16bit(3, 7, 4)
PYV376 = 26374  # encode_pysyntax_to_16bit(3, 7, 6)
PYV38  = 26624  # encode_pysyntax_to_16bit(3, 8, 0)  - Python3.8

5.1.2.2. Encoding Support

5.1.2.3. ISSTR

Provides a tuple with valid string types:

if PYV35Plus:
    ISSTR = (str, bytes)  #: string and unicode

    #: Superpose for generic Python3 compatibility.
    unicode = str  # @ReservedAssignment

elif PYV3X:
    ISSTR = (str, bytes)  #: string and unicode

    #: Superpose for generic Python3 compatibility.
    unicode = str  # @ReservedAssignment

elif PYV27X:
    ISSTR = (str, unicode)  #: string and unicode
    unicode = unicode  # @ReservedAssignment

For the application by “in”:

if type(s) in ISSTR:
    ...

5.1.2.4. ISSTRBASE

Provides a tuple with valid basic string types basestring - for Python3 (str,), and for Python2 (str, unicode,):

if PYV35Plus:
   ISSTRBASE = (str,)  #: str

elif PYV3X:
   ISSTRBASE = (str,)  #: str

elif PYV27X:
    ISSTRBASE = (str, unicode,)  #: basestr

For the application by “in”:

if type(s) in ISSTRBASE:
    ...

5.1.2.5. unicode

Provides a syntax release dependent type reference unicode, which could be used as a common type:

if PYV35Plus:
    unicode = str  # @ReservedAssignment

elif PYV3X:
    unicode = str  # @ReservedAssignment

elif PYV27X:
    unicode = unicode  # @ReservedAssignment

5.1.3. Attributes

The following attributes are part of the official interface and could be used alternively to the access functions.

5.1.3.1. PYVxyz

Bit dynamic evaluated encoding of the current Python version. The value is set automatic for the current performing Python interpreter during the load of the module.

Vxyz := xxxyyyyyzzzzzzzz

xxx      := major version
yyyyy    := minor version
zzzzzzzz := build

For example for the version "3.6.5": ::

xxx      = 3 = 011
yyyyy    = 6 = 00110
zzzzzzzz = 5 = 00000101

xxxyyyyyzzzzzzzz = 26117 = 0b0110011000000101

The value is evaluated by the call:

PYVxyz = encode_pysyntax_to_16bit(*sys.version_info[:3])

This enables the binary checks with pre-defined integer values for fast frequent evaluation:

if Vxyz & 26117:  # 0b0110011000000101
   # this is version 3.6.5

if Vxyz & 26112:  # 0b0110011000000000
   # this is version 3.6

if Vxyz < 26112:
   # this is pre-version 3.6, e.g. 3.5.x

The use of explicit numerical reference values is here perfectly applicable because of the static nature of version dependencies.

For example the syntax release of Python-3.6.5:

1
2
3
4
5
# xxx:      011
# yyyyy:    00110
# zzzzzzzz: 00000101

PYVxyz = 0b0110011000000101 = 0x6605 = 26117

5.1.3.2. PYV27X

Adjust to current major syntax version - Python2.7.x.

1
2
3
PYV27X = PYVxyz >= PYV27 and PYVxyz < PYV3 #: Python2.7
if PYV27X:
    ISSTR = (str, unicode)  #: string and unicode

The definition includes also the helper variables ISSTR and unicode, which support basic multiplatform encoding checks for Python2 and Python3.

5.1.3.3. PYV3X

Adjust to current syntax version - Python3.X.Y

1
2
3
4
5
6
7
PYV3X = PYVxyz >= PYV3  #: Python3
if PYV3X:
    PYV35Plus = True
    ISSTR = (str, bytes)  #: string and unicode

    #: Superpose for generic Python3 compatibility.
    unicode = str  # @ReservedAssignment

The definition includes also the helper variables ISSTR and unicode, which support basic multiplatform encoding checks for Python2 and Python3.

5.1.3.4. PYV3X

Adjust to current syntax version - Python3.0 <= X <= Python3.3.X

5.1.3.5. PYV35Plus

The numeric identifier of the supported Python versions. In most of cases the Python version 3 is considered to contain a sustainable stable feature set from the version 3.5 onward. Thus the value of PYV35Plus is set as a runtime constant during load.

PYV35Plus := (
     True  # Python3.5+
   | False # Python2.7
)

wirh the implementation:

PYV35Plus = PYVxyz >= PYV35  #: Python3.5+
if PYV35Plus:
    ...

5.1.4. Functions

5.1.4.1. decode_pysyntax_16bit_to_str

pythonids.__init__.decode_pysyntax_16bit_to_str(xyz, form='%d.%d.%d')[source]

Decodes the compressed version 16bit integer bitmask into the corresponding string.

The optional format string form provides the formatting of a 3-value interger tuple. E.g. form=”%02d.%02d.%03d”.

Due to the spared error checks the string has to be correct!

Examples:

decode_pysyntax_16bit_to_str(26117)   =>  '3.6.5'
decode_pysyntax_16bit_to_str(PYV365)  =>  '3.6.5'

5.1.4.2. decode_pysyntax_16bit_to_tuple

pythonids.__init__.decode_pysyntax_16bit_to_tuple(xyz)[source]

Decodes the compressed version 16bit integer bitmask into the corresponding tuple of integer values.

Examples:

decode_pysyntax_16bit_to_tuple(26117)   =>  (3, 6, 5)
decode_pysyntax_16bit_to_tuple(PYV365)  =>  (3, 6, 5)

5.1.4.3. decode_pysyntax_16bit_to_tuple_str

pythonids.__init__.decode_pysyntax_16bit_to_tuple_str(xyz)[source]

Decodes the compressed version 16bit integer bitmask into the corresponding tuple of integer values.

Examples:

decode_pysyntax_16bit_to_tuple_str(26117)   =>  ('3', '6', '5')
decode_pysyntax_16bit_to_tuple_str(PYV365)  =>  ('3', '6', '5')

5.1.4.4. decode_pysyntax_str_to_num

pythonids.__init__.decode_pysyntax_str_to_num(v)[source]

Split a version string separated by ‘.’ into an integer tuple.

decode_pysyntax_str_to_num('1.22.17')  =>  (1, 22, 17)

A tiny utility - frequently required.

Parameters

string 'x.y.z'. (Version) –

Returns

Integer tuple (x, y, z)

Raises

ValueError –

5.1.4.5. encode_pysyntax_to_16bit

pythonids.__init__.encode_pysyntax_to_16bit(x=0, y=0, z=0)[source]

Encodes the version by calculating the 16bit integer bitmask for the provided Python release values.

Parameters

  • x –

    The major version number.

    0 <= x

0 <= x0 < 8  # internal low-level 16-bit optimization threshold

  • y –

    The minor version number.

    0 <= y < 32

  • z –

    The numeric relase-build tag.

    0 <= z < 256

Returns

The bitmask.

Raises

pass-through –

Examples:

Calculates the 16bit-mask for the Python release:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
from pythonids import PYV35, PYVxyz  # pre-defined values

from pythonids import encode_pysyntax_to_16bit      # function interface for the calculation
                                       # of bit masks for releases

# calculate non-pre-defined values
pyv33 = encode_pysyntax_to_16bit(3, 3)
pyv362 = encode_pysyntax_to_16bit(3, 6, 2)

if PYVxyz & pyv33 == pyv33:
 # do s.th....

elif PyVxyz & pyv362 == pyv362:
 # do s.th. else...

elif PyVxyz >= PYV35:
 # do s.th. else...

else:
 # support the minimal and/or legacy spec....

or

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
from pythonids import PYV35, PYVxyz  # pre-defined values

from pythonids import encode_pysyntax_to_16bit      # function interface for the calculation
                                       # of bit masks for releases

# calculate non-pre-defined values
pyv3 = encode_pysyntax_to_16bit(3,)
pyv33 = encode_pysyntax_to_16bit(3, 3)
pyv362 = encode_pysyntax_to_16bit(3, 6, 2)

if PYVxyz & pyv3 == pyv3:
   if PYVxyz & pyv33 == pyv33:
      # do s.th....

elif PyVxyz & pyv362 == pyv362:
   # do s.th. else...

elif PyVxyz >= PYV35:
   # do s.th. else...

else:
   # support the minimal and/or legacy spec....

For example from sys.version_info:

x = sys.version_info[0]  # uses 3bits:  x: 0-7
y = sys.version_info[1]  # uses 5bits:  y: 0-31
z = sys.version_info[2]  # uses 8bits:  z: 0-255

resulting in:

.. parsed-literal::

   Vxyz = 0bxxxyyyyyzzzzzzzz

For example:

x, y, z = (3, 6, 5)

self.bits = (3, 5, 8)

# => result = 0b 011 00110 00000101
# => result = 0b0110011000000101 =  26,117

5.1.5. Exceptions

exception pythonids.__init__.PythonIDsError[source]

Subsystem PythonIDs.

exception pythonids.__init__.PythonIDsImplementationError[source]

Python implementation not supported.