serialnumbers package

Common declarations

author

  1. Voillat

date

2022-05-23 Creation

copyright

Dassym SA 2021

EXCLUSION_CHAR = '-'

Char to specify an exclusion range

LASTNUM_RE = re.compile('(.*\\D)?(\\d+)(\\D+)?')

Regex to decompose a serial number

RANGE_CHAR = '-'

Char to separate the first and last serial numbers of range

RANGE_SEP_CHAR = ';'

Default char to separate the two ranges

SIZE_CHAR = ':'

Char to separate the first serial number and the size of range

The class SerialNumber

class SerialNumber(sn_or_prefix, number=None, suffix=None, padSize=1, padChar='0')[source]

Bases: object

Class representing a serial number.

Parameters

  • sn_or_prefix (str) – Serial number or serial number prefix. If number and suffix are None, then this parameter is interpreted as a string describing a serial number.

  • number (int) – The number (default = None)

  • suffix (str) – Serial number suffix (default = None)

  • padSize (int) – Minimum digit group size (default = 1)

  • padChar (str) – Filler character for digit group (default = ‘0’)

A serial number consists of 3 parts:

  • The prefix: all the characters located before the last group of digits (number)

  • The number: the last group of digits, this part can be incremented

  • The suffix: all the characters located after the last group of digits (number)

String

Prefix

Number

Suffix

A001X

A

1

X

001X

None

1

X

A001

A

1

None

A12X01

A12X

1

None
cmp(other)[source]

Compare two serial numbers

Parameters

other (SerialNumber) – the other serial number

Returns

-1, if other is smaller ; 0, if both are equal ; 1 otherwise.

>>> SerialNumber('x001Z').cmp(SerialNumber('x001Z'))
0

>>> SerialNumber('x001Z').cmp(SerialNumber('x002Z'))
-1

>>> SerialNumber('x001Z').cmp(SerialNumber('a001Z'))
1
classmethod compare(a, b)[source]

Compare two serial numbers

Parameters
Returns

-1, if a < b ; 0, if a == b, 1 otherwise

>>> SerialNumber.compare(SerialNumber('X02'), SerialNumber('X01'))
1
countTo(other, inc=1)[source]

Counts the number of SNs in the interval with another SN

Both serial numbers must be in the same range (see inSameRange()).

Parameters
Returns

The number of SNs in the interval with the other SN.

>>> SerialNumber('x001Z').countTo(SerialNumber('x020Z'))
20

>>> SerialNumber('x001Z').countTo(SerialNumber('y020Z'))
Traceback (most recent call last):
...
ValueError: The other serial number (y020Z) is not in the same range (x001Z)!
classmethod explode(s)[source]

Decomposes the string of characters into three constituent parts of a serial number.

Parameters

s (str) – String describing the serial number.

Returns

A 3-tuple of containing the prefix, number, and suffix.

Return type

tuple

The 3 elements of a serial number are:

  • The prefix: all the characters located before the last group of digits

  • The number: the last group of digits

  • The suffix: all the characters located after the last group of digits

See also: LASTNUM_RE See also: The grammar rule for serial number.

>>> SerialNumber.explode('abc123-0045Z')
('abc123-', 45, 'Z', 4)

>>> SerialNumber.explode('0045')
(None, 45, None, 4)

>>> SerialNumber.explode('abc123-0045')
('abc123-', 45, None, 4)

>>> SerialNumber.explode('0045Z')
(None, 45, 'Z', 4)
classmethod fromString(s)[source]

Creates a SerialNumber object from a string.

Parameters

s (str) – The serial number as a character string.

Returns

The created serial number.

Return type

SerialNumber

See also the grammar rule for serial number.

>>> str(SerialNumber.fromString('abc123-0045Z'))
'abc123-0045Z'
genCount(count, inc=1)[source]

Returns a generator for a list of count serial numbers.

>>> print(list(SerialNumber('x001Z').genCount(10)))
[SerialNumber('x001Z'), SerialNumber('x002Z'), ..., SerialNumber('x010Z')]
genEnd(end, inc=1)[source]

Returns a generator for a list of serial numbers according the end.

>>> print(list(SerialNumber('x001Z').genEnd(SerialNumber('x020Z'))))
[SerialNumber('x001Z'), SerialNumber('x002Z'), ..., SerialNumber('x020Z')]
inSameRange(other)[source]

Checks if itself is in the same range as the other serial number.

Two serial numbers are considered to be from the same range if their prefixes and suffixes are the same.

Parameters

other (SerialNumber) – the other serial number.

Returns

True, if itself is in the same range as the other serial number.

>>> SerialNumber('abc123-0045Z').inSameRange(SerialNumber('abc123-', 102, 'Z', 4))
True
>>> SerialNumber('abc123-0045X').inSameRange(SerialNumber('abc123-', 102, 'Z', 4))
False
isNext(other, inc=1)[source]

Checks if the other serial number is the next.

Parameters

other (SerialNumber) – the other serial number.

Returns

True, if the other serial number is the next.

>>> SerialNumber('abc123-0044Z').isNext(SerialNumber('abc123-', 45, 'Z', 4))
True
classmethod listFromString(s, inc=1, sep=';')[source]

Reads a character string containing the definition of one or more serial number ranges.

Parameters

  • s (str) – the character string containing the definition of the serial number ranges

  • inc (int) – The increment to compute numbers, default = 1

  • sep (str) – Serial number ranges separator character (default = RANGE_SEP_CHAR)

See also the grammar rules for lists and for exclusion ranges

>>> SerialNumber.listFromString('X01:10;X50-X59;-X02:2')
[SerialNumber('X01'), SerialNumber('X04'), ..., SerialNumber('X10'), SerialNumber('X50'), ..., SerialNumber('X59')]
next(inc=1)[source]

Returns the next serial number

Parameters

inc (int) – Increment to compute the next serial number

Returns

the next serial number according increment.

Return type

SerialNumber

>>> SerialNumber('abc123-0044Z').next(2)
SerialNumber('abc123-0046Z')
prev(inc=1)[source]

Returns the previous serial number

Parameters

inc (int) – Increment to compute the next serial number

Return SerialNumber

the previous serial number according increment.

>>> SerialNumber('x0044Z').prev(2)
SerialNumber('x0042Z')
range(a, b=None, c=1)[source]

Creates a range of serial numbers

:param int a : If b isn’t defined the stop index of the range, then the star index :param int b : If defined, the stop index of the range :param int c : Step (increment) to compute serial number

>>> list(SerialNumber('x010Z').range(10))
[SerialNumber('x010Z'), SerialNumber('x011Z'), ..., SerialNumber('x019Z')]

>>> list(SerialNumber('x010Z').range(2,5))
[SerialNumber('x012Z'), SerialNumber('x013Z'), ..., SerialNumber('x015Z')]
toString()[source]

Returns the serial number as a string.

Returns

the serial number as a string.

>>> SerialNumber(None, number=123, suffix='A', padSize=5, padChar='#').toString()
'##123A'

The class SerialNumberRange

class SerialNumberRange(first, count=None, last=None, inc=1)[source]

Bases: object

Class representing a range of serial numbers

A serial number range consists of a sequence of consecutive serial numbers

Parameters

  • first (SerialNumber) – The first serial number of range

  • count (int) – If defined, the size of range

  • last (SerialNumber) – If defined, the last serial number of range

  • inc (int) – The increment to compute numbers, default = 1

EXCLUDE = False
property count
property first
classmethod fromStartCount(first, count, inc=1)[source]
classmethod fromStartEnd(first, last, inc=1)[source]
classmethod fromString(s, inc=1)[source]

Creates a range of serial numbers from a string.

Parameters

  • s (str) – The string describing the serial number range

  • inc (int) – The increment to compute numbers, default = 1

Returns

The created serial numbers range or exclusion range

Return type

SerialNumberRange, SerialNumberXRange

A serial number range is defined by giving the starting and ending serial numbers separated by a hyphen (-), or by giving the starting serial number and the number of numbers separated by a colon (:). If the range definition string starts with a hyphen (-), then it is an exclusion range and will result in an object of class SerialNumberXRange.

See also the grammar rule for lists

>>> list(SerialNumberRange.fromString('X001:10'))
[SerialNumber('X001'), SerialNumber('X002'), ..., SerialNumber('X010')]

>>> list(SerialNumberRange.fromString('X001-X010'))
[SerialNumber('X001'), SerialNumber('X002'), ..., SerialNumber('X010')]

>>> list(SerialNumberRange.fromString('X001'))
[SerialNumber('X001')]

>>> SerialNumberRange.fromString('-X05:2')
SerialNumberXRange('-X05-X06')
property inc
property last
toString()[source]
toStringFirstCount()[source]

Represents the serial number range in the format: A:C, where A and C are, respectively, the first serial number and the number of serial numbers in the range

Returns

The Representation of the serial number range in the format: A:C

Return type

str

>>> SerialNumberRange(SerialNumber('X001'), 10).toStringFirstCount()
'X001:10'
toStringFirstLast()[source]

Represents the serial number range in the format: A-B, where A and B are, respectively, the first and last serial number in the range

Returns

The Representation of the serial number range in the format: A-B

Return type

str

>>> SerialNumberRange(SerialNumber('X001'), 10).toStringFirstLast()
'X001-X010'

The class SerialNumberXRange

class SerialNumberXRange(first, count=None, last=None, inc=1)[source]

Bases: SerialNumberRange

EXCLUDE = True
toStringFirstCount()[source]

Represents the serial number range in the format: A:C, where A and C are, respectively, the first serial number and the number of serial numbers in the range

Returns

The Representation of the serial number range in the format: A:C

Return type

str

>>> SerialNumberRange(SerialNumber('X001'), 10).toStringFirstCount()
'X001:10'
toStringFirstLast()[source]
>>> str(SerialNumberXRange.fromString('X01:3'))
'-X01-X03'

The class SerialNumberlist

class SerialNumberList(snlist=None, inc=1, sep=';')[source]

Bases: object

Class for a list of serial number ranges.

Parameters

  • snlist (str or list) – Characters string containing the definition of one or more serial number ranges or list of SerialNumber or SerialNumberRange.

  • inc (int) – The increment to compute numbers, default = 1

  • sep (str) – Serial number ranges separator character (default = RANGE_SEP_CHAR)

Note

If snlist is a list, then all elements must be of the same class, either SerialNumber or SerialNumberRange.

>>> list(SerialNumberList('X01:10;X50-X59;-X02:2').ranges)
[SerialNumberRange('X01'), SerialNumberRange('X04-X10'), SerialNumberRange('X50-X59')]
addNumber(sn)[source]

Add a serial number into ranges list.

Parameters

sn (SerialNumber) – SN to addRange.

addRange(snRange, force=False)[source]

Add a serial number range into the list.

Parameters

  • snRange (SerialNumberRange) – The range to addRange

  • force (bool) – If true, forces the addition even if one or more SNs are already in the list. Otherwise the exception ValueError is issued.

>>> SerialNumberList('X01:5;X10:5').addRange(SerialNumberRange.fromString('X06:4')).ranges
[SerialNumberRange('X01-X14')]
clear()[source]
getNumbers()[source]
property inc
property numbers
property ranges
classmethod snListFromString(s, inc=1, sep=';')[source]

Reads a string containing the definition of one or more serial number ranges and convert it into a list of SNs.

Parameters

  • s (str) – Characters string containing the definition of one or more serial number ranges.

  • inc (int) – The increment to compute numbers, default = 1

  • sep (str) – Serial number ranges separator character (default = RANGE_SEP_CHAR)

Returns

The created list of serial numbers ranges

Return type

SerialNumberList

classmethod snRangesFromList(snlist, inc=1, nosort=False)[source]

Convert a list of SN to a list of SN ranges

Parameters

  • snlist (list,tuple) – The list of serial numbers to convert

  • inc (int) – The increment to compute numbers, default = 1

Returns

The list of SerialNumberRange

Return type

list

>>> list(SerialNumberList.snRangesFromList(SerialNumber.listFromString('X01:10;X50-X59;-X02:2')))
[SerialNumberRange('X01'), SerialNumberRange('X04-X10'), SerialNumberRange('X50-X59')]
toString()[source]