API#

Module contents#

Python JMAP Bindings.

class python_jmap.Date(value=None)#

Bases: str

Helper type for generating JMAP spec-compliant dates.

The time-secfrac MUST always be omitted if zero, and any letters in the string (e.g., “T” and “Z”) MUST be uppercase. For example, “2014-10-30T14:12:00+08:00”.

Example: >>> d = Date(datetime(2022, 10, 30, 14, 12, 0)) >>> print(d) “2022-10-30T14:12:00” >>> d = Date(datetime(2022, 10, 30, 14, 12, 0, 500000)) >>> print(d) “2022-10-30T14:12:00.500”

Parameters:: value (datetime | None) –
Return type:: Date

class python_jmap.ID(identifier=None)#

Bases: str

Helper type for generating JMAP spec-compliant ID strings.

Example: >>> id = ID(“test_id”) >>> print(id) test_id

Parameters:: identifier (str | None) –
Return type:: ID

static generate(length=255)#

Generate a safe ID.

A safe ID starts with an alphabetical character, contains only alphanumeric, hyphen, and underscore characters, does not contain only digits, and does not contain the sequence “NIL”.

Parameters:: length (int) – The length of the ID to generate. Must be between 2 and 255. Defaults to 255.
Returns:: A new ID instance that meets the criteria for a safe ID.
Return type:: ID

static is_safe(id_str)#

Check if the ID is “safe”.

A safe ID does not start with a dash or digit, does not contain only digits, does not contain the sequence “NIL”, and does not differ only in case.

Parameters:: id_str (str) – The ID to check.
Returns:: True if the ID is safe, False otherwise.
Return type:: bool

static validate(identifier)#

Validate an identifier.

The identifier must be between 1 and 255 characters in length and contain only alphanumeric, hyphen, and underscore characters.

Parameters:: identifier (str) – The identifier to validate.
Raises:: ValueError – If the identifier is not valid.
Return type:: None

class python_jmap.Int(value)#

Bases: int

Helper type for generating JMAP spec-compliant ints.

Integer must in the range -2^53+1 to 2^53-1.

Example: >>> x = Int(10) >>> print(x) 10

Parameters:: value (int) –
Return type:: Int

class python_jmap.UInt(value)#

Bases: Int

Helper type for generating JMAP spec-compliant uints.

Integer where the value MUST be in the range 0 to 2^53-1.

Example: >>> x = UInt(10) >>> print(x) 10

Parameters:: value (int) –
Return type:: UInt

class python_jmap.UTCDate(value=None)#

Bases: str

Helper type for generating JMAP spec-compliant UTC dates.

For example, “2014-10-30T06:12:00Z”.

Example: >>> d = UTCDate(datetime(2022, 10, 30, 14, 12, 0, tzinfo=timezone.utc)) >>> print(d) “2022-10-30T14:12:00Z”

Parameters:: value (datetime | None) –
Return type:: UTCDate

python_jmap.types.date module#

JMAP datetime types.

Spec: https://jmap.io/spec-core.html#the-date-and-utcdate-data-types

class python_jmap.types.date.Date(value=None)#

Bases: str

Helper type for generating JMAP spec-compliant dates.

The time-secfrac MUST always be omitted if zero, and any letters in the string (e.g., “T” and “Z”) MUST be uppercase. For example, “2014-10-30T14:12:00+08:00”.

Example: >>> d = Date(datetime(2022, 10, 30, 14, 12, 0)) >>> print(d) “2022-10-30T14:12:00” >>> d = Date(datetime(2022, 10, 30, 14, 12, 0, 500000)) >>> print(d) “2022-10-30T14:12:00.500”

Parameters:: value (datetime | None) –
Return type:: Date

class python_jmap.types.date.UTCDate(value=None)#

Bases: str

Helper type for generating JMAP spec-compliant UTC dates.

For example, “2014-10-30T06:12:00Z”.

Example: >>> d = UTCDate(datetime(2022, 10, 30, 14, 12, 0, tzinfo=timezone.utc)) >>> print(d) “2022-10-30T14:12:00Z”

Parameters:: value (datetime | None) –
Return type:: UTCDate

python_jmap.types.id module#

JMAP Identifier type.

Spec: https://jmap.io/spec-core.html#the-id-data-type

class python_jmap.types.id.ID(identifier=None)#

Bases: str

Helper type for generating JMAP spec-compliant ID strings.

Example: >>> id = ID(“test_id”) >>> print(id) test_id

Parameters:: identifier (str | None) –
Return type:: ID

static generate(length=255)#

Generate a safe ID.

A safe ID starts with an alphabetical character, contains only alphanumeric, hyphen, and underscore characters, does not contain only digits, and does not contain the sequence “NIL”.

Parameters:: length (int) – The length of the ID to generate. Must be between 2 and 255. Defaults to 255.
Returns:: A new ID instance that meets the criteria for a safe ID.
Return type:: ID

static is_safe(id_str)#

Check if the ID is “safe”.

A safe ID does not start with a dash or digit, does not contain only digits, does not contain the sequence “NIL”, and does not differ only in case.

Parameters:: id_str (str) – The ID to check.
Returns:: True if the ID is safe, False otherwise.
Return type:: bool

static validate(identifier)#

Validate an identifier.

The identifier must be between 1 and 255 characters in length and contain only alphanumeric, hyphen, and underscore characters.

Parameters:: identifier (str) – The identifier to validate.
Raises:: ValueError – If the identifier is not valid.
Return type:: None

python_jmap.types.int module#

JMAP integer types.

Spec: https://jmap.io/spec-core.html#the-int-and-uint-data-types

class python_jmap.types.int.Int(value)#

Bases: int

Helper type for generating JMAP spec-compliant ints.

Integer must in the range -2^53+1 to 2^53-1.

Example: >>> x = Int(10) >>> print(x) 10

Parameters:: value (int) –
Return type:: Int

class python_jmap.types.int.UInt(value)#

Bases: Int

Helper type for generating JMAP spec-compliant uints.

Integer where the value MUST be in the range 0 to 2^53-1.

Example: >>> x = UInt(10) >>> print(x) 10

Parameters:: value (int) –
Return type:: UInt

Module contents#

JMAP types and dataclasses.

class python_jmap.types.Date(value=None)#

Bases: str

Helper type for generating JMAP spec-compliant dates.

The time-secfrac MUST always be omitted if zero, and any letters in the string (e.g., “T” and “Z”) MUST be uppercase. For example, “2014-10-30T14:12:00+08:00”.

Example: >>> d = Date(datetime(2022, 10, 30, 14, 12, 0)) >>> print(d) “2022-10-30T14:12:00” >>> d = Date(datetime(2022, 10, 30, 14, 12, 0, 500000)) >>> print(d) “2022-10-30T14:12:00.500”

Parameters:: value (datetime | None) –
Return type:: Date

class python_jmap.types.ID(identifier=None)#

Bases: str

Helper type for generating JMAP spec-compliant ID strings.

Example: >>> id = ID(“test_id”) >>> print(id) test_id

Parameters:: identifier (str | None) –
Return type:: ID

static generate(length=255)#

Generate a safe ID.

A safe ID starts with an alphabetical character, contains only alphanumeric, hyphen, and underscore characters, does not contain only digits, and does not contain the sequence “NIL”.

Parameters:: length (int) – The length of the ID to generate. Must be between 2 and 255. Defaults to 255.
Returns:: A new ID instance that meets the criteria for a safe ID.
Return type:: ID

static is_safe(id_str)#

Check if the ID is “safe”.

A safe ID does not start with a dash or digit, does not contain only digits, does not contain the sequence “NIL”, and does not differ only in case.

Parameters:: id_str (str) – The ID to check.
Returns:: True if the ID is safe, False otherwise.
Return type:: bool

static validate(identifier)#

Validate an identifier.

The identifier must be between 1 and 255 characters in length and contain only alphanumeric, hyphen, and underscore characters.

Parameters:: identifier (str) – The identifier to validate.
Raises:: ValueError – If the identifier is not valid.
Return type:: None

class python_jmap.types.Int(value)#

Bases: int

Helper type for generating JMAP spec-compliant ints.

Integer must in the range -2^53+1 to 2^53-1.

Example: >>> x = Int(10) >>> print(x) 10

Parameters:: value (int) –
Return type:: Int

class python_jmap.types.UInt(value)#

Bases: Int

Helper type for generating JMAP spec-compliant uints.

Integer where the value MUST be in the range 0 to 2^53-1.

Example: >>> x = UInt(10) >>> print(x) 10

Parameters:: value (int) –
Return type:: UInt

class python_jmap.types.UTCDate(value=None)#

Bases: str

Helper type for generating JMAP spec-compliant UTC dates.

For example, “2014-10-30T06:12:00Z”.

Example: >>> d = UTCDate(datetime(2022, 10, 30, 14, 12, 0, tzinfo=timezone.utc)) >>> print(d) “2022-10-30T14:12:00Z”

Parameters:: value (datetime | None) –
Return type:: UTCDate