open-xpd-uuid 1.1.0
A library for creating and managing globally-unique open-xpd-uuid namespaces for product declarations.
License: Apache-2.0
Requires Python: <4.0,>=3.9

# open-xpd-uuid-lib
A library of common functions used when creating and managing open-xpd-uuid, 
a common, globally-unique name space (uuid) for Product Declarations, including HPDs and EPDs, 
to help users find all environmental and health information related to a single product.
# Open xPD UUID (short readable GUIDs)
`open-xpd-uuid` is a string that consists of 8 or 10 (8+2) alpha-numeric characters and any number of dashes. 
For example: `123ABCED`, `123ABCEDAR`, `ASB21M01`, `avbDK93S`, `-AB-11-cc-Ll---`.
GUIDs that consists of the following characters `1234567890ABCDEFGHJKMNPRQRSTUVWXYZ` (`L` and `O` are not mentioned) 
are called "canonical". For example: `12345678`, `ABCDEFG1`, `123ABCEDAR`.
GUIDs that consists of 10 characters represent 8-character guid with appended 2-character checksum.
Checksum allows to detect 1-character entry errors and character swaps, and most other errors.
## Character treatment
* `-` or dash - is ignored
* `L` or `l` or `I` or `i` - is treated as `1`
* `O` or `o` - is treated as `0`(zero)
 
# Install
`pip install open-xpd-uuid-lib`

# Supported versions
- The library is tested with the following Python versions:
  - Python 3.9
  - Python 3.10
  - Python 3.11
  - Python 3.12
  - Python 3.13
  - Python 3.14
- The minimal supported Python version is 3.9.
- Compatibility with future Python 3.x versions is expected but not guaranteed.

# Usage
## Generate short readable GUID
```pycon
>>> from cqd import open_xpd_uuid
>>> open_xpd_uuid.generate()
'JKGEE5PN'
```
## Generate short readable GUID starting with specific characters set (prefix)
```pycon
>>> from cqd import open_xpd_uuid
>>> open_xpd_uuid.generate('CQD')
'CQD55PG0'
```

If you wish to issue your own openEPD IDs, you can request any three-symbol prefix that is not already reserved.

- "EC3" is reserved for BuildingTransparency.org
- "EST" is reserved for generic estimates
- "CQD" and "WAP" are reserved for WAP Sustainability
- "PCR" is reserved for designating product category rules
- "UL" is reserved for UL Sustainability

To request your own prefix, please email open-epd-forum@c-change-labs.com.

## Sanitize short readable GUIDs
Use `sanitize` to replace ambiguous chars(_0,o,O,1,L,l,I,i_) with correct ones and remove dashes(_-_).
This function is useful to turn guid received from a user into a canonical one.

For example: `as-b2-lm-oL` -> `ASB21M01`
```pycon
>>> from cqd import open_xpd_uuid
>>> open_xpd_uuid.sanitize('as-b2-lm-oL')
'ASB21M01'
```
## Validate short readable GUID
Use `validate` to validate short readable GUID and get error description if the GUID is not valid.
`validate` __accepts only__ "canonical" GUIDs: use `sanitize` function to make them "canonical".
```pycon
>>> from cqd import open_xpd_uuid
>>> sanitized_guid = open_xpd_uuid.sanitize('as-b2-lm-oL')
>>> sanitized_guid
'ASB21M01'
>>> open_xpd_uuid.validate(sanitized_guid)
# no exception - the `sanitized_guid` is valid

>>> try:
...     open_xpd_uuid.validate('as-b2-lm-oL')
... except open_xpd_uuid.GuidValidationError as e:
...     print(e)
...     
`guid` length must be 8 characters long
```

## Generate and use checksum
```pycon
>>> from cqd import open_xpd_uuid
>>> guid = open_xpd_uuid.generate()
'JKGEE5PN'
>>> checksum = open_xpd_uuid.checksum(guid)
'ME'
>>> guid_with_checksum = guid + checksum
'JKGEE5PNME'
>>> short_link = 'cqd.io/e/' + guid_with_checksum
'cqd.io/e/JKGEE5PNME'
```