comparing 0becde3f1302f63c30e953cf4224c2f8dc6048b2 and dantic on dwn.poxiao-labs.work/atpasser

src/atpasser/nsid/__init__.py

···

       12
       12
        
               Initalizes an NSID object.

     

       13
       13
        
       

     

       14
       14
        
               Parameters:

     

       15
       15
       +
                   domainAuthority (list): Domain Authority as list.

     

       16
       16
       +
                   domainAuthorityAsText (str): Domain Authority as text.

     

       17
       17
       +
                   name (str): The name.

     

       18
       18
       +
                   fragment (str | none): The fragment.

     

       15
       19
        
                   nsid (str): The NSID.

     

       16
       20
        
               """

     

       17
       21

+5 -5

docs/roadmap.md

···

       7
       7
        
       |Data Model|**Will be rewritten**|

     

       8
       8
        
       |Lexicon|**Will be rewritten with Data Model part**|

     

       9
       9
        
       |Cryptography||

     

       10
       10
       -
       |Accounts||

     

       10
       10
       +
       |Accounts|**Will implemented in Server and Client library**|

     

       11
       11
        
       |Repository||

     

       12
       12
        
       |Blobs|`blob` Naming blobs' CID only|

     

       13
       13
        
       |Labels||

     

       14
       14
       -
       |HTTP API||

     

       15
       15
       -
       |OAuth||

     

       16
       16
       -
       |Event Stream||

     

       17
       17
       -
       |Sync||

     

       14
       14
       +
       |HTTP API|**Will implemented in Server and Client library**|

     

       15
       15
       +
       |OAuth|**Will implemented in Server and Client library**|

     

       16
       16
       +
       |Event Stream|**Will implemented in Server and Client library**|

     

       17
       17
       +
       |Sync|**Will implemented in Server and Client library**|

     

       18
       18
        
       |DID|`did` Almost done|

     

       19
       19
        
       |Handle|`handle` Almost done|

     

       20
       20
        
       |NSID|`nsid` Almost done|

-54

src/atpasser/did/__init__.py

···

       1
       1
       -
       import re

     

       2
       2
       -
       from pyld import jsonld

     

       3
       3
       -
       

     

       4
       4
       -
       

     

       5
       5
       -
       class DID:

     

       6
       6
       -
           """

     

       7
       7
       -
           A class representing a DID.

     

       8
       8
       -
       

     

       9
       9
       -
           Attributes:

     

       10
       10
       -
               uri (str): The DID URI.

     

       11
       11
       -
           """

     

       12
       12
       -
       

     

       13
       13
       -
           def __init__(self, uri: str) -> None:

     

       14
       14
       -
               """

     

       15
       15
       -
               Initalizes an DID object.

     

       16
       16
       -
       

     

       17
       17
       -
               Parameters:

     

       18
       18
       -
                   uri (str): The DID URI.

     

       19
       19
       -
               """

     

       20
       20
       -
               pattern = re.compile("^did:[a-z]+:[a-zA-Z0-9._:%-]*[a-zA-Z0-9._-]$")

     

       21
       21
       -
               patternMatch = pattern.match(uri)

     

       22
       22
       -
               if patternMatch and len(uri) <= 2048:

     

       23
       23
       -
                   self.uri = patternMatch[0]

     

       24
       24
       -
               else:

     

       25
       25
       -
                   raise ValueError

     

       26
       26
       -
       

     

       27
       27
       -
           def __str__(self) -> str:

     

       28
       28
       -
               """

     

       29
       29
       -
               Convert the TID to a string by given the URI.

     

       30
       30
       -
               """

     

       31
       31
       -
               return self.uri

     

       32
       32
       -
       

     

       33
       33
       -
           def __eq__(self, value: object, /) -> bool:

     

       34
       34
       -
               """

     

       35
       35
       -
               Check if the 2 values are exactly the same.

     

       36
       36
       -
               """

     

       37
       37
       -
               if isinstance(value, DID):

     

       38
       38
       -
                   return str(self) == str(value)

     

       39
       39
       -
               else:

     

       40
       40
       -
                   return False

     

       41
       41
       -
       

     

       42
       42
       -
           def fetch(self):

     

       43
       43
       -
               """

     

       44
       44
       -
               Fetch the metadata of the DID.

     

       45
       45
       -
       

     

       46
       46
       -
               Returns:

     

       47
       47
       -
                   list: the pseudo-list which can be read by `PyLD` library

     

       48
       48
       -
               """

     

       49
       49
       -
               if self.uri.startswith("did:plc:"):

     

       50
       50
       -
                   return jsonld.expand(f"https://plc.directory/{self.uri}")

     

       51
       51
       -
               elif self.uri.startswith("did:web"):

     

       52
       52
       -
                   return jsonld.expand(

     

       53
       53
       -
                       f"https://{self.uri.replace("did:web:","")}/.well-known/did.json"

     

       54
       54
       -
                   )

+61 -17

src/atpasser/uri/handle.py

···

       32
       32
        
               """

     

       33
       33
        
       

     

       34
       34
        
               if len(handle) > 253:

     

       35
       35
       -
                   raise InvalidHandleError(handle, "exceeds maximum length", f"Handle length {len(handle)} exceeds maximum allowed length of 253 characters")

     

       35
       35
       +
                   raise InvalidHandleError(

     

       36
       36
       +
                       handle,

     

       37
       37
       +
                       "exceeds maximum length",

     

       38
       38
       +
                       f"Handle length {len(handle)} exceeds maximum allowed length of 253 characters",

     

       39
       39
       +
                   )

     

       36
       40
        
       

     

       37
       41
        
               labels = handle.lower().split(".")

     

       38
       42
        
       

     

       39
       43
        
               if len(labels) < 2:

     

       40
       40
       -
                   raise InvalidHandleError(handle, "invalid format", "Handle must contain at least one dot separator, e.g., 'example.com'")

     

       44
       44
       +
                   raise InvalidHandleError(

     

       45
       45
       +
                       handle,

     

       46
       46
       +
                       "invalid format",

     

       47
       47
       +
                       "Handle must contain at least one dot separator, e.g., 'example.com'",

     

       48
       48
       +
                   )

     

       41
       49
        
       

     

       42
       50
        
               if labels[0] == "" or labels[-1] == "":

     

       43
       43
       -
                   raise InvalidHandleError(handle, "invalid format", "Handle cannot start or end with a dot")

     

       51
       51
       +
                   raise InvalidHandleError(

     

       52
       52
       +
                       handle, "invalid format", "Handle cannot start or end with a dot"

     

       53
       53
       +
                   )

     

       44
       54
        
       

     

       45
       55
        
               for i, label in enumerate(labels):

     

       46
       56
        
                   if len(label) not in range(1, 64):

     

       47
       47
       -
                       raise InvalidHandleError(handle, "segment length error", f"Handle segment {i+1} length {len(label)} is not in the 1-63 character range")

     

       57
       57
       +
                       raise InvalidHandleError(

     

       58
       58
       +
                           handle,

     

       59
       59
       +
                           "segment length error",

     

       60
       60
       +
                           f"Handle segment {i+1} length {len(label)} is not in the 1-63 character range",

     

       61
       61
       +
                       )

     

       48
       62
        
                   charset = set(label)

     

       49
       63
        
                   validset = set("abcdefghijklmnopqrstuvwxyz0123456789-")

     

       50
       64
        
                   if not charset.issubset(validset):

     

       51
       65
        
                       invalid_chars = charset - validset

     

       52
       52
       -
                       raise InvalidHandleError(handle, "contains invalid characters", f"Handle segment {i+1} contains invalid characters: {', '.join(invalid_chars)}")

     

       66
       66
       +
                       raise InvalidHandleError(

     

       67
       67
       +
                           handle,

     

       68
       68
       +
                           "contains invalid characters",

     

       69
       69
       +
                           f"Handle segment {i+1} contains invalid characters: {', '.join(invalid_chars)}",

     

       70
       70
       +
                       )

     

       53
       71
        
                   if label.startswith("-") or label.endswith("-"):

     

       54
       54
       -
                       raise InvalidHandleError(handle, "invalid format", f"Handle segment {i+1} cannot start or end with a hyphen")

     

       72
       72
       +
                       raise InvalidHandleError(

     

       73
       73
       +
                           handle,

     

       74
       74
       +
                           "invalid format",

     

       75
       75
       +
                           f"Handle segment {i+1} cannot start or end with a hyphen",

     

       76
       76
       +
                       )

     

       55
       77
        
       

     

       56
       78
        
               tld = labels[-1]

     

       57
       79
        
               if tld[0] in "0123456789":

     

       58
       58
       -
                   raise InvalidHandleError(handle, "invalid format", "Handle's top-level domain cannot start with a digit")

     

       80
       80
       +
                   raise InvalidHandleError(

     

       81
       81
       +
                       handle,

     

       82
       82
       +
                       "invalid format",

     

       83
       83
       +
                       "Handle's top-level domain cannot start with a digit",

     

       84
       84
       +
                   )

     

       59
       85
        
       

     

       60
       86
        
               self.handle = handle

     

       61
       87
        
       

     
···

       111
       137
        
                       answers = dns.resolver.resolve("_atproto." + self.handle, "TXT")

     

       112
       138
        
                   except Exception as e:

     

       113
       139
        
                       answers = []

     

       114
       114
       -
                       

     

       140
       140
       +
       

     

       115
       141
        
                   for answer in answers:

     

       116
       142
        
                       answer_str = str(answer)

     

       117
       143
        
                       if answer_str.startswith('"did='):

     
···

       122
       148
        
                               # Continue trying other records or methods

     

       123
       149
        
                               continue

     

       124
       150
        
                           except Exception as e:

     

       125
       125
       -
                               raise ResolutionError(self.handle, "DNS resolution", f"Error parsing DNS TXT record: {str(e)}")

     

       126
       126
       -
                   

     

       151
       151
       +
                               raise ResolutionError(

     

       152
       152
       +
                                   self.handle,

     

       153
       153
       +
                                   "DNS resolution",

     

       154
       154
       +
                                   f"Error parsing DNS TXT record: {str(e)}",

     

       155
       155
       +
                               )

     

       156
       156
       +
       

     

       127
       157
        
                   # If DNS resolution fails, try HTTP method

     

       128
       158
        
                   try:

     

       129
       129
       -
                       response = requests.get(f"https://{self.handle}/.well-known/atproto-did")

     

       159
       159
       +
                       response = requests.get(

     

       160
       160
       +
                           f"https://{self.handle}/.well-known/atproto-did"

     

       161
       161
       +
                       )

     

       130
       162
        
                       if response.status_code // 100 != 2:

     

       131
       163
        
                           return None

     

       132
       132
       -
                           

     

       164
       164
       +
       

     

       133
       165
        
                       # Some websites may return incorrect Content-Type, so here we only warn without throwing an exception

     

       134
       166
        
                       content_type = response.headers.get("Content-Type")

     

       135
       167
        
                       if content_type != "text/plain" and content_type:

     

       136
       168
        
                           # Log warning but don't block processing

     

       137
       169
        
                           pass

     

       138
       138
       -
                           

     

       170
       170
       +
       

     

       139
       171
        
                       try:

     

       140
       172
        
                           return DID(response.text.strip())

     

       141
       173
        
                       except InvalidDIDError:

     

       142
       174
        
                           return None

     

       143
       175
        
                   except requests.RequestException as e:

     

       144
       144
       -
                       raise ResolutionError(self.handle, "HTTP request", f"Error requesting well-known endpoint: {str(e)}")

     

       176
       176
       +
                       raise ResolutionError(

     

       177
       177
       +
                           self.handle,

     

       178
       178
       +
                           "HTTP request",

     

       179
       179
       +
                           f"Error requesting well-known endpoint: {str(e)}",

     

       180
       180
       +
                       )

     

       145
       181
        
                   except Exception as e:

     

       146
       146
       -
                       raise ResolutionError(self.handle, "HTTP parsing", f"Error parsing HTTP response: {str(e)}")

     

       147
       147
       -
                       

     

       182
       182
       +
                       raise ResolutionError(

     

       183
       183
       +
                           self.handle,

     

       184
       184
       +
                           "HTTP parsing",

     

       185
       185
       +
                           f"Error parsing HTTP response: {str(e)}",

     

       186
       186
       +
                       )

     

       187
       187
       +
       

     

       148
       188
        
               except Exception as e:

     

       149
       189
        
                   if isinstance(e, ResolutionError):

     

       150
       190
        
                       raise

     

       151
       151
       -
                   raise ResolutionError(self.handle, "resolution", f"Unknown error occurred while resolving Handle: {str(e)}")

     

       191
       191
       +
                   raise ResolutionError(

     

       192
       192
       +
                       self.handle,

     

       193
       193
       +
                       "resolution",

     

       194
       194
       +
                       f"Unknown error occurred while resolving Handle: {str(e)}",

     

       195
       195
       +
                   )

+82 -20

src/atpasser/uri/nsid.py

···

       36
       36
        
               if "#" in nsid:

     

       37
       37
        
                   parts = nsid.split("#", 1)

     

       38
       38
        
                   if len(parts) != 2:

     

       39
       39
       -
                       raise InvalidNSIDError(nsid, "invalid format", "NSID fragment format is incorrect")

     

       39
       39
       +
                       raise InvalidNSIDError(

     

       40
       40
       +
                           nsid, "invalid format", "NSID fragment format is incorrect"

     

       41
       41
       +
                       )

     

       40
       42
        
                   nsidWithoutFragment, fragment = parts

     

       41
       43
        
               else:

     

       42
       44
        
                   nsidWithoutFragment, fragment = nsid, None

     
···

       45
       47
        
               if not set([x for x in nsidWithoutFragment]).issubset(

     

       46
       48
        
                   set([chr(i) for i in range(0x80)])

     

       47
       49
        
               ):

     

       48
       48
       -
                   raise InvalidNSIDError(nsid, "contains invalid characters", "NSID must only contain ASCII characters")

     

       50
       50
       +
                   raise InvalidNSIDError(

     

       51
       51
       +
                       nsid,

     

       52
       52
       +
                       "contains invalid characters",

     

       53
       53
       +
                       "NSID must only contain ASCII characters",

     

       54
       54
       +
                   )

     

       49
       55
        
       

     

       50
       56
        
               # Check length

     

       51
       57
        
               if len(nsidWithoutFragment) > 317:

     

       52
       52
       -
                   raise InvalidNSIDError(nsid, "exceeds maximum length", f"NSID length {len(nsidWithoutFragment)} exceeds maximum allowed length of 317 characters")

     

       58
       58
       +
                   raise InvalidNSIDError(

     

       59
       59
       +
                       nsid,

     

       60
       60
       +
                       "exceeds maximum length",

     

       61
       61
       +
                       f"NSID length {len(nsidWithoutFragment)} exceeds maximum allowed length of 317 characters",

     

       62
       62
       +
                   )

     

       53
       63
        
       

     

       54
       64
        
               segments = nsidWithoutFragment.split(".")

     

       55
       65
        
       

     

       56
       66
        
               # Check for leading or trailing dots

     

       57
       67
        
               if nsidWithoutFragment.startswith(".") or nsidWithoutFragment.endswith("."):

     

       58
       58
       -
                   raise InvalidNSIDError(nsid, "invalid format", "NSID cannot start or end with a dot")

     

       68
       68
       +
                   raise InvalidNSIDError(

     

       69
       69
       +
                       nsid, "invalid format", "NSID cannot start or end with a dot"

     

       70
       70
       +
                   )

     

       59
       71
        
       

     

       60
       72
        
               # Check segment count

     

       61
       73
        
               if len(segments) < 3:

     

       62
       62
       -
                   raise InvalidNSIDError(nsid, "invalid format", f"NSID must contain at least 3 segments, currently has {len(segments)}")

     

       74
       74
       +
                   raise InvalidNSIDError(

     

       75
       75
       +
                       nsid,

     

       76
       76
       +
                       "invalid format",

     

       77
       77
       +
                       f"NSID must contain at least 3 segments, currently has {len(segments)}",

     

       78
       78
       +
                   )

     

       63
       79
        
       

     

       64
       80
        
               domainAuthority = [segment.lower() for segment in segments[0:-1]]

     

       65
       81
        
       

     

       66
       82
        
               # Check domain authority length

     

       67
       83
        
               if len(".".join(domainAuthority)) > 253:

     

       68
       68
       -
                   raise InvalidNSIDError(nsid, "domain authority length exceeds limit", "Domain authority part length exceeds 253 characters")

     

       84
       84
       +
                   raise InvalidNSIDError(

     

       85
       85
       +
                       nsid,

     

       86
       86
       +
                       "domain authority length exceeds limit",

     

       87
       87
       +
                       "Domain authority part length exceeds 253 characters",

     

       88
       88
       +
                   )

     

       69
       89
        
       

     

       70
       90
        
               # Check each domain segment

     

       71
       91
        
               for i, segment in enumerate(domainAuthority):

     

       72
       92
        
                   if len(segment) > 63 or segment == "":

     

       73
       73
       -
                       raise InvalidNSIDError(nsid, "segment length error", f"Domain authority segment {i+1} length is not in the 1-63 character range")

     

       93
       93
       +
                       raise InvalidNSIDError(

     

       94
       94
       +
                           nsid,

     

       95
       95
       +
                           "segment length error",

     

       96
       96
       +
                           f"Domain authority segment {i+1} length is not in the 1-63 character range",

     

       97
       97
       +
                       )

     

       74
       98
        
                   if not set(segment).issubset(set("abcdefghijklmnopqrstuvwxyz0123456789-")):

     

       75
       75
       -
                       invalid_chars = set(segment) - set("abcdefghijklmnopqrstuvwxyz0123456789-")

     

       76
       76
       -
                       raise InvalidNSIDError(nsid, "contains invalid characters", f"Domain authority segment {i+1} contains invalid characters: {', '.join(invalid_chars)}")

     

       99
       99
       +
                       invalid_chars = set(segment) - set(

     

       100
       100
       +
                           "abcdefghijklmnopqrstuvwxyz0123456789-"

     

       101
       101
       +
                       )

     

       102
       102
       +
                       raise InvalidNSIDError(

     

       103
       103
       +
                           nsid,

     

       104
       104
       +
                           "contains invalid characters",

     

       105
       105
       +
                           f"Domain authority segment {i+1} contains invalid characters: {', '.join(invalid_chars)}",

     

       106
       106
       +
                       )

     

       77
       107
        
                   if segment.startswith("-") or segment.endswith("-"):

     

       78
       78
       -
                       raise InvalidNSIDError(nsid, "invalid format", f"Domain authority segment {i+1} cannot start or end with a hyphen")

     

       79
       79
       -
                       

     

       108
       108
       +
                       raise InvalidNSIDError(

     

       109
       109
       +
                           nsid,

     

       110
       110
       +
                           "invalid format",

     

       111
       111
       +
                           f"Domain authority segment {i+1} cannot start or end with a hyphen",

     

       112
       112
       +
                       )

     

       113
       113
       +
       

     

       80
       114
        
               # Check if top-level domain starts with a digit

     

       81
       115
        
               if segments[0][0] in "0123456789":

     

       82
       82
       -
                   raise InvalidNSIDError(nsid, "invalid format", "NSID's top-level domain cannot start with a digit")

     

       116
       116
       +
                   raise InvalidNSIDError(

     

       117
       117
       +
                       nsid,

     

       118
       118
       +
                       "invalid format",

     

       119
       119
       +
                       "NSID's top-level domain cannot start with a digit",

     

       120
       120
       +
                   )

     

       83
       121
        
       

     

       84
       122
        
               self.domainAuthority = domainAuthority

     

       85
       123
        
               self.domainAuthorityAsText = ".".join(domainAuthority)

     
···

       88
       126
        
       

     

       89
       127
        
               # Check name

     

       90
       128
        
               if name == "" or len(name) > 63:

     

       91
       91
       -
                   raise InvalidNSIDError(nsid, "name length error", "NSID name cannot be empty and length cannot exceed 63 characters")

     

       129
       129
       +
                   raise InvalidNSIDError(

     

       130
       130
       +
                       nsid,

     

       131
       131
       +
                       "name length error",

     

       132
       132
       +
                       "NSID name cannot be empty and length cannot exceed 63 characters",

     

       133
       133
       +
                   )

     

       92
       134
        
       

     

       93
       135
        
               if not set(name).issubset(

     

       94
       136
        
                   set("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789")

     

       95
       137
        
               ):

     

       96
       96
       -
                   invalid_chars = set(name) - set("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789")

     

       97
       97
       -
                   raise InvalidNSIDError(nsid, "contains invalid characters", f"NSID name contains invalid characters: {', '.join(invalid_chars)}")

     

       138
       138
       +
                   invalid_chars = set(name) - set(

     

       139
       139
       +
                       "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"

     

       140
       140
       +
                   )

     

       141
       141
       +
                   raise InvalidNSIDError(

     

       142
       142
       +
                       nsid,

     

       143
       143
       +
                       "contains invalid characters",

     

       144
       144
       +
                       f"NSID name contains invalid characters: {', '.join(invalid_chars)}",

     

       145
       145
       +
                   )

     

       98
       146
        
       

     

       99
       147
        
               if name[0] in "0123456789":

     

       100
       100
       -
                   raise InvalidNSIDError(nsid, "invalid format", "NSID name cannot start with a digit")

     

       148
       148
       +
                   raise InvalidNSIDError(

     

       149
       149
       +
                       nsid, "invalid format", "NSID name cannot start with a digit"

     

       150
       150
       +
                   )

     

       101
       151
        
       

     

       102
       152
        
               self.name = name

     

       103
       153
        
       

     

       104
       154
        
               # Check fragment

     

       105
       155
        
               if fragment != None:

     

       106
       156
        
                   if fragment == "" or len(fragment) > 63:

     

       107
       107
       -
                       raise InvalidNSIDError(nsid, "fragment length error", "NSID fragment cannot be empty and length cannot exceed 63 characters")

     

       157
       157
       +
                       raise InvalidNSIDError(

     

       158
       158
       +
                           nsid,

     

       159
       159
       +
                           "fragment length error",

     

       160
       160
       +
                           "NSID fragment cannot be empty and length cannot exceed 63 characters",

     

       161
       161
       +
                       )

     

       108
       162
        
       

     

       109
       163
        
                   if not set(fragment).issubset(

     

       110
       164
        
                       set("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789")

     

       111
       165
        
                   ):

     

       112
       112
       -
                       invalid_chars = set(fragment) - set("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789")

     

       113
       113
       -
                       raise InvalidNSIDError(nsid, "contains invalid characters", f"NSID fragment contains invalid characters: {', '.join(invalid_chars)}")

     

       166
       166
       +
                       invalid_chars = set(fragment) - set(

     

       167
       167
       +
                           "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"

     

       168
       168
       +
                       )

     

       169
       169
       +
                       raise InvalidNSIDError(

     

       170
       170
       +
                           nsid,

     

       171
       171
       +
                           "contains invalid characters",

     

       172
       172
       +
                           f"NSID fragment contains invalid characters: {', '.join(invalid_chars)}",

     

       173
       173
       +
                       )

     

       114
       174
        
       

     

       115
       175
        
                   if fragment[0] in "0123456789":

     

       116
       116
       -
                       raise InvalidNSIDError(nsid, "invalid format", "NSID fragment cannot start with a digit")

     

       176
       176
       +
                       raise InvalidNSIDError(

     

       177
       177
       +
                           nsid, "invalid format", "NSID fragment cannot start with a digit"

     

       178
       178
       +
                       )

     

       117
       179
        
       

     

       118
       180
        
                   self.fragment = fragment

     

       119
       181

-92

src/atpasser/uri/restricted.py

···

       1
       1
       -
       from . import handle, nsid

     

       2
       2
       -
       from . import rkey as rKey

     

       3
       3
       -
       from . import URI

     

       4
       4
       -
       from .exceptions import InvalidRestrictedURIError, InvalidURIError

     

       5
       5
       -
       

     

       6
       6
       -
       

     

       7
       7
       -
       class RestrictedURI(URI):

     

       8
       8
       -
           """A class representing a restricted AT Protocol URI for record access.

     

       9
       9
       -
       

     

       10
       10
       -
           RestrictedURIs provide a specialized form of AT Protocol URIs that specifically

     

       11
       11
       -
           address records within repositories. They follow the format 'at://authority/collection/rkey'

     

       12
       12
       -
           where collection identifies the record type (via NSID) and rkey identifies the specific

     

       13
       13
       -
           record instance. This format is commonly used for referencing specific social records

     

       14
       14
       -
           like posts, profiles, and other user-generated content.

     

       15
       15
       -
       

     

       16
       16
       -
           Attributes:

     

       17
       17
       -
               collection (atpasser.uri.NSID): The record collection identified by NSID.

     

       18
       18
       -
               rkey (atpasser.uri.RKey): The record key identifying a specific record instance.

     

       19
       19
       -
           """

     

       20
       20
       -
       

     

       21
       21
       -
           def __init__(self, uri: str) -> None:

     

       22
       22
       -
               """Initializes a restricted URI with validation.

     

       23
       23
       -
       

     

       24
       24
       -
               Parses and validates an AT Protocol URI specifically for record access.

     

       25
       25
       -
               Restricted URIs must have a valid authority (DID or handle), may include

     

       26
       26
       -
               a collection (NSID), and optionally a record key (rkey). Query parameters

     

       27
       27
       -
               and fragments are not allowed in restricted URIs.

     

       28
       28
       -
       

     

       29
       29
       -
               Args:

     

       30
       30
       -
                   uri (str): The AT Protocol URI string to parse as a restricted URI.

     

       31
       31
       -
       

     

       32
       32
       -
               Raises:

     

       33
       33
       -
                   InvalidRestrictedURIError: If the URI has query parameters or fragments, invalid authority,

     

       34
       34
       -
                                           or too many path segments for a restricted URI format.

     

       35
       35
       -
                   InvalidURIError: If the underlying URI validation fails.

     

       36
       36
       -
               """

     

       37
       37
       -
       

     

       38
       38
       -
               try:

     

       39
       39
       -
                   super().__init__(uri)

     

       40
       40
       -
               except InvalidURIError:

     

       41
       41
       -
                   raise

     

       42
       42
       -
               except Exception as e:

     

       43
       43
       -
                   raise InvalidURIError(

     

       44
       44
       -
                       uri, "base URI validation failed", f"Failed to parse base URI: {str(e)}"

     

       45
       45
       -
                   )

     

       46
       46
       -
       

     

       47
       47
       -
               if self.query is not None:

     

       48
       48
       -
                   raise InvalidRestrictedURIError(

     

       49
       49
       -
                       uri,

     

       50
       50
       -
                       "query parameters not supported",

     

       51
       51
       -
                       "Restricted URI cannot contain query parameters",

     

       52
       52
       -
                   )

     

       53
       53
       -
       

     

       54
       54
       -
               if self.fragment is not None:

     

       55
       55
       -
                   raise InvalidRestrictedURIError(

     

       56
       56
       -
                       uri,

     

       57
       57
       -
                       "fragments not supported",

     

       58
       58
       -
                       "Restricted URI cannot contain fragments",

     

       59
       59
       -
                   )

     

       60
       60
       -
       

     

       61
       61
       -
               if self.authority is None:

     

       62
       62
       -
                   raise InvalidRestrictedURIError(

     

       63
       63
       -
                       uri,

     

       64
       64
       -
                       "invalid authority",

     

       65
       65
       -
                       "Restricted URI must contain a valid DID or Handle",

     

       66
       66
       -
                   )

     

       67
       67
       -
       

     

       68
       68
       -
               try:

     

       69
       69
       -
                   if len(self.path) == 0:

     

       70
       70
       -
                       self.collection, self.rkey = None, None

     

       71
       71
       -
       

     

       72
       72
       -
                   elif len(self.path) == 1:

     

       73
       73
       -
                       self.collection = nsid.NSID(self.path[0])

     

       74
       74
       -
                       self.rkey = None

     

       75
       75
       -
       

     

       76
       76
       -
                   elif len(self.path) == 2:

     

       77
       77
       -
                       self.collection = nsid.NSID(self.path[0])

     

       78
       78
       -
                       self.rkey = rKey.RKey(self.path[1])

     

       79
       79
       -
                   else:

     

       80
       80
       -
                       raise InvalidRestrictedURIError(

     

       81
       81
       -
                           uri,

     

       82
       82
       -
                           "too many path segments",

     

       83
       83
       -
                           f"Restricted URI can have at most 2 path segments, currently has {len(self.path)}",

     

       84
       84
       -
                       )

     

       85
       85
       -
               except Exception as e:

     

       86
       86
       -
                   if isinstance(e, (InvalidRestrictedURIError, InvalidURIError)):

     

       87
       87
       -
                       raise

     

       88
       88
       -
                   raise InvalidRestrictedURIError(

     

       89
       89
       -
                       uri,

     

       90
       90
       -
                       "parsing error",

     

       91
       91
       -
                       f"Error occurred while parsing Restricted URI: {str(e)}",

     

       92
       92
       -
                   )

-136

src/atpasser/uri/tid.py

···

       1
       1
       -
       import datetime, random

     

       2
       2
       -
       

     

       3
       3
       -
       

     

       4
       4
       -
       class TID:

     

       5
       5
       -
           """A class representing a TID (Time-based Identifier) in the AT Protocol.

     

       6
       6
       -
       

     

       7
       7
       -
           TIDs are time-based identifiers used for ordering and uniquely identifying

     

       8
       8
       -
           records in the AT Protocol. They combine a microsecond-precision timestamp

     

       9
       9
       -
           with a clock identifier to ensure uniqueness even when multiple records

     

       10
       10
       -
           are created in the same microsecond. TIDs are sortable and provide both

     

       11
       11
       -
           temporal ordering and uniqueness guarantees.

     

       12
       12
       -
       

     

       13
       13
       -
           Attributes:

     

       14
       14
       -
               timestamp (datetime.datetime): The timestamp component of the TID.

     

       15
       15
       -
               clockIdentifier (int): Clock identifier (0-1023) for disambiguation.

     

       16
       16
       -
           """

     

       17
       17
       -
       

     

       18
       18
       -
           def __init__(

     

       19
       19
       -
               self, time: datetime.datetime | None = None, clockIdentifier: int | None = None

     

       20
       20
       -
           ) -> None:

     

       21
       21
       -
               """Initializes a TID object with timestamp and clock identifier.

     

       22
       22
       -
       

     

       23
       23
       -
               Creates a new TID with the specified timestamp and clock identifier.

     

       24
       24
       -
               If no timestamp is provided, uses the current time. If no clock identifier

     

       25
       25
       -
               is provided, generates a random value between 0-1023.

     

       26
       26
       -
       

     

       27
       27
       -
               Args:

     

       28
       28
       -
                   time (datetime.datetime, optional): The timestamp for the TID.

     

       29
       29
       -
                       Defaults to current time if not provided.

     

       30
       30
       -
                   clockIdentifier (int, optional): Clock identifier (0-1023) for

     

       31
       31
       -
                       disambiguation. Defaults to random value if not provided.

     

       32
       32
       -
               """

     

       33
       33
       -
               if time == None:

     

       34
       34
       -
                   self.timestamp = datetime.datetime.now()

     

       35
       35
       -
               else:

     

       36
       36
       -
                   self.timestamp = time

     

       37
       37
       -
               if clockIdentifier == None:

     

       38
       38
       -
                   self.clockIdentifier = random.randrange(0, 1024)

     

       39
       39
       -
               else:

     

       40
       40
       -
                   self.clockIdentifier = clockIdentifier

     

       41
       41
       -
       

     

       42
       42
       -
           def __int__(self):

     

       43
       43
       -
               """Convert the TID to its integer representation.

     

       44
       44
       -
       

     

       45
       45
       -
               Combines the timestamp (in microseconds) and clock identifier into

     

       46
       46
       -
               a single 64-bit integer where the high bits represent the timestamp

     

       47
       47
       -
               and the low 10 bits represent the clock identifier.

     

       48
       48
       -
       

     

       49
       49
       -
               Returns:

     

       50
       50
       -
                   int: The integer representation of the TID.

     

       51
       51
       -
               """

     

       52
       52
       -
               timestamp = int(self.timestamp.timestamp() * 1000000)

     

       53
       53
       -
               return timestamp * 1024 + self.clockIdentifier

     

       54
       54
       -
       

     

       55
       55
       -
           def __str__(self):

     

       56
       56
       -
               """Convert the TID to a base32-sortable string representation.

     

       57
       57
       -
       

     

       58
       58
       -
               Encodes the TID as a base32 string using a custom character set that

     

       59
       59
       -
               maintains lexicographical sort order corresponding to temporal order.

     

       60
       60
       -
               This format is commonly used in the AT Protocol for compact,

     

       61
       61
       -
               sortable identifiers.

     

       62
       62
       -
       

     

       63
       63
       -
               Returns:

     

       64
       64
       -
                   str: The base32 string representation of the TID.

     

       65
       65
       -
               """

     

       66
       66
       -
               integer = int(self)

     

       67
       67
       -
               binary = f"{integer:065b}"

     

       68
       68
       -
               return "".join(

     

       69
       69
       -
                   [

     

       70
       70
       -
                       "234567abcdefghijklmnopqrstuvwxyz"[int(binary[i : i + 5], base=2)]

     

       71
       71
       -
                       for i in range(0, len(binary), 5)

     

       72
       72
       -
                   ]

     

       73
       73
       -
               )

     

       74
       74
       -
       

     

       75
       75
       -
           def __eq__(self, value: object, /) -> bool:

     

       76
       76
       -
               """Check if two TID objects represent the same identifier.

     

       77
       77
       -
       

     

       78
       78
       -
               Args:

     

       79
       79
       -
                   value (object): The object to compare with.

     

       80
       80
       -
       

     

       81
       81
       -
               Returns:

     

       82
       82
       -
                   bool: True if the objects represent the same TID, False otherwise.

     

       83
       83
       -
               """

     

       84
       84
       -
               if isinstance(value, TID):

     

       85
       85
       -
                   return int(self) == int(value)

     

       86
       86
       -
               else:

     

       87
       87
       -
                   return False

     

       88
       88
       -
       

     

       89
       89
       -
       

     

       90
       90
       -
       def importTIDfromInteger(value: int | None = None):

     

       91
       91
       -
           """Create a TID object from an integer representation.

     

       92
       92
       -
       

     

       93
       93
       -
           Converts a 64-bit integer back into a TID object by extracting the

     

       94
       94
       -
           timestamp and clock identifier components. If no value is provided,

     

       95
       95
       -
           creates a TID for the current time.

     

       96
       96
       -
       

     

       97
       97
       -
           Args:

     

       98
       98
       -
               value (int, optional): The integer value to convert to a TID.

     

       99
       99
       -
                   Defaults to creating a TID for the current time if not provided.

     

       100
       100
       -
       

     

       101
       101
       -
           Returns:

     

       102
       102
       -
               TID: The TID object created from the integer value.

     

       103
       103
       -
           """

     

       104
       104
       -
           if value == None:

     

       105
       105
       -
               value = int(TID())

     

       106
       106
       -
           clockIdentifier = value % 1024

     

       107
       107
       -
           timestamp = (value >> 10) / 1000000

     

       108
       108
       -
           return TID(datetime.datetime.fromtimestamp(timestamp), clockIdentifier)

     

       109
       109
       -
       

     

       110
       110
       -
       

     

       111
       111
       -
       def importTIDfromBase32(value: str | None = None):

     

       112
       112
       -
           """Create a TID object from a base32 string representation.

     

       113
       113
       -
       

     

       114
       114
       -
           Converts a base32-encoded TID string back into a TID object by decoding

     

       115
       115
       -
           the string to its integer representation and then extracting the timestamp

     

       116
       116
       -
           and clock identifier components. If no value is provided, creates a TID

     

       117
       117
       -
           for the current time.

     

       118
       118
       -
       

     

       119
       119
       -
           Args:

     

       120
       120
       -
               value (str, optional): The base32 string to convert to a TID.

     

       121
       121
       -
                   Defaults to creating a TID for the current time if not provided.

     

       122
       122
       -
       

     

       123
       123
       -
           Returns:

     

       124
       124
       -
               TID: The TID object created from the base32 string.

     

       125
       125
       -
           """

     

       126
       126
       -
           if value == None:

     

       127
       127
       -
               value = str(TID())

     

       128
       128
       -
           b32s = "234567abcdefghijklmnopqrstuvwxyz"

     

       129
       129
       -
           return importTIDfromInteger(

     

       130
       130
       -
               sum(

     

       131
       131
       -
                   [

     

       132
       132
       -
                       b32s.find(value[i]) * (32 ** (len(value) - i - 1))

     

       133
       133
       -
                       for i in range(len(value))

     

       134
       134
       -
                   ]

     

       135
       135
       -
               )

     

       136
       136
       -
           )

src/atpasser/uri/__init__.py

···

       144
       144
        
                           "JSONPath parsing failed",

     

       145
       145
        
                           f"Failed to parse JSONPath fragment '{fragment}': {str(e)}",

     

       146
       146
        
                       )

     

       147
       147
       +
               else:

     

       148
       148
       +
                   self.fragment = None

     

       149
       149
       +
                   self.fragmentAsText = None

     

       147
       150
        
       

     

       148
       151
        
               if query != None:

     

       149
       152
        
                   try:

-182

src/atpasser/data/decoder.py

···

       1
       1
       -
       """

     

       2
       2
       -
       JSON decoder for ATProto data model.

     

       3
       3
       -
       

     

       4
       4
       -
       This module provides a JSON decoder that handles ATProto-specific data types,

     

       5
       5
       -
       including bytes, CID links, and typed objects.

     

       6
       6
       -
       """

     

       7
       7
       -
       

     

       8
       8
       -
       import base64

     

       9
       9
       -
       import json

     

       10
       10
       -
       from typing import Any, Callable, Dict, Optional

     

       11
       11
       -
       from cid import CIDv0, CIDv1, make_cid

     

       12
       12
       -
       

     

       13
       13
       -
       

     

       14
       14
       -
       class JsonDecoder(json.JSONDecoder):

     

       15
       15
       -
           """A JSON decoder that supports ATProto data types.

     

       16
       16
       -
       

     

       17
       17
       -
           This decoder extends the standard JSON decoder to handle ATProto-specific

     

       18
       18
       -
           data types, including bytes, CID links, and typed objects.

     

       19
       19
       -
       

     

       20
       20
       -
           Attributes:

     

       21
       21
       -
               type_hook_registry: Registry for type-specific hooks.

     

       22
       22
       -
               encoding: The encoding to use for string deserialization.

     

       23
       23
       -
           """

     

       24
       24
       -
       

     

       25
       25
       -
           def __init__(

     

       26
       26
       -
               self,

     

       27
       27
       -
               *,

     

       28
       28
       -
               object_hook: Optional[Callable[[Dict[str, Any]], Any]] = None,

     

       29
       29
       -
               type_hook_registry: Optional[Any] = None,

     

       30
       30
       -
               type_processor_registry: Optional[Any] = None,

     

       31
       31
       -
               encoding: str = "utf-8",

     

       32
       32
       -
               **kwargs: Any,

     

       33
       33
       -
           ) -> None:

     

       34
       34
       -
               """Initialize the JSON decoder.

     

       35
       35
       -
       

     

       36
       36
       -
               Args:

     

       37
       37
       -
                   object_hook: Optional function to call with each decoded object.

     

       38
       38
       -
                   type_hook_registry: Registry for type-specific hooks.

     

       39
       39
       -
                   type_processor_registry: Registry for type-specific processors.

     

       40
       40
       -
                   encoding: The encoding to use for string deserialization.

     

       41
       41
       -
                   **kwargs: Additional keyword arguments to pass to the parent class.

     

       42
       42
       -
               """

     

       43
       43
       -
               # Use the type processor registry if provided, otherwise use the type hook registry

     

       44
       44
       -
               if type_processor_registry is not None:

     

       45
       45
       -
                   type_hook_registry = type_processor_registry.to_hook_registry()

     

       46
       46
       -
               elif type_hook_registry is None:

     

       47
       47
       -
                   from .hooks import get_global_registry

     

       48
       48
       -
       

     

       49
       49
       -
                   type_hook_registry = get_global_registry()

     

       50
       50
       -
       

     

       51
       51
       -
               # Create a combined object hook that calls both the custom hook and our hook

     

       52
       52
       -
               combined_hook = self._create_combined_hook(object_hook, type_hook_registry)

     

       53
       53
       -
       

     

       54
       54
       -
               super().__init__(object_hook=combined_hook, **kwargs)

     

       55
       55
       -
               self.type_hook_registry = type_hook_registry

     

       56
       56
       -
               self.type_processor_registry = type_processor_registry

     

       57
       57
       -
               self.encoding = encoding

     

       58
       58
       -
       

     

       59
       59
       -
           def _create_combined_hook(

     

       60
       60
       -
               self,

     

       61
       61
       -
               custom_hook: Optional[Callable[[Dict[str, Any]], Any]],

     

       62
       62
       -
               type_hook_registry: Optional[Any],

     

       63
       63
       -
           ) -> Callable[[Dict[str, Any]], Any]:

     

       64
       64
       -
               """Create a combined object hook function.

     

       65
       65
       -
       

     

       66
       66
       -
               Args:

     

       67
       67
       -
                   custom_hook: Optional custom object hook function.

     

       68
       68
       -
                   type_hook_registry: Registry for type-specific hooks.

     

       69
       69
       -
       

     

       70
       70
       -
               Returns:

     

       71
       71
       -
                   A combined object hook function.

     

       72
       72
       -
               """

     

       73
       73
       -
       

     

       74
       74
       -
               def combined_hook(obj: Dict[str, Any]) -> Any:

     

       75
       75
       -
                   # First, apply our ATProto-specific decoding

     

       76
       76
       -
                   decoded_obj = self._atproto_object_hook(obj)

     

       77
       77
       -
       

     

       78
       78
       -
                   # Then, apply the custom hook if provided

     

       79
       79
       -
                   if custom_hook is not None:

     

       80
       80
       -
                       decoded_obj = custom_hook(decoded_obj)

     

       81
       81
       -
       

     

       82
       82
       -
                   return decoded_obj

     

       83
       83
       -
       

     

       84
       84
       -
               return combined_hook

     

       85
       85
       -
       

     

       86
       86
       -
           def _atproto_object_hook(self, obj: Dict[str, Any]) -> Any:

     

       87
       87
       -
               """Handle ATProto-specific object decoding.

     

       88
       88
       -
       

     

       89
       89
       -
               Args:

     

       90
       90
       -
                   obj: The object to decode.

     

       91
       91
       -
       

     

       92
       92
       -
               Returns:

     

       93
       93
       -
                   The decoded object.

     

       94
       94
       -
               """

     

       95
       95
       -
               # Handle $bytes key (RFC-4648 base64 decoding)

     

       96
       96
       -
               if "$bytes" in obj:

     

       97
       97
       -
                   if len(obj) != 1:

     

       98
       98
       -
                       # If there are other keys, this is invalid

     

       99
       99
       -
                       raise ValueError(f"Invalid $bytes object: {obj}")

     

       100
       100
       -
                   return base64.b64decode(obj["$bytes"].encode(self.encoding))

     

       101
       101
       -
       

     

       102
       102
       -
               # Handle $link key (CID parsing)

     

       103
       103
       -
               elif "$link" in obj:

     

       104
       104
       -
                   if len(obj) != 1:

     

       105
       105
       -
                       # If there are other keys, this is invalid

     

       106
       106
       -
                       raise ValueError(f"Invalid $link object: {obj}")

     

       107
       107
       -
                   return make_cid(obj["$link"])

     

       108
       108
       -
       

     

       109
       109
       -
               # Handle $type key (typed objects)

     

       110
       110
       -
               elif "$type" in obj:

     

       111
       111
       -
                   type_value = obj["$type"]

     

       112
       112
       -
                   remaining_obj = {k: v for k, v in obj.items() if k != "$type"}

     

       113
       113
       -
       

     

       114
       114
       -
                   # Check if there's a registered type handler

     

       115
       115
       -
                   if self.type_hook_registry is not None:

     

       116
       116
       -
                       handler = self.type_hook_registry.get_handler(type_value)

     

       117
       117
       -
                       if handler is not None:

     

       118
       118
       -
                           return handler(remaining_obj)

     

       119
       119
       -
       

     

       120
       120
       -
                   # If no handler is registered, return a typed object

     

       121
       121
       -
                   return TypedObject(type_value, remaining_obj)

     

       122
       122
       -
       

     

       123
       123
       -
               # Handle nested objects recursively

     

       124
       124
       -
               elif isinstance(obj, dict):

     

       125
       125
       -
                   return {

     

       126
       126
       -
                       k: self._atproto_object_hook(v) if isinstance(v, dict) else v

     

       127
       127
       -
                       for k, v in obj.items()

     

       128
       128
       -
                   }

     

       129
       129
       -
       

     

       130
       130
       -
               return obj

     

       131
       131
       -
       

     

       132
       132
       -
       

     

       133
       133
       -
       class TypedObject:

     

       134
       134
       -
           """A typed object in the ATProto data model.

     

       135
       135
       -
       

     

       136
       136
       -
           This class represents an object with a $type field in the ATProto data model.

     

       137
       137
       -
       

     

       138
       138
       -
           Attributes:

     

       139
       139
       -
               type: The type of the object.

     

       140
       140
       -
               data: The data associated with the object.

     

       141
       141
       -
           """

     

       142
       142
       -
       

     

       143
       143
       -
           def __init__(self, type_name: str, data: Dict[str, Any]) -> None:

     

       144
       144
       -
               """Initialize a typed object.

     

       145
       145
       -
       

     

       146
       146
       -
               Args:

     

       147
       147
       -
                   type_name: The type of the object.

     

       148
       148
       -
                   data: The data associated with the object.

     

       149
       149
       -
               """

     

       150
       150
       -
               self.type_name = type_name

     

       151
       151
       -
               self.data = data

     

       152
       152
       -
       

     

       153
       153
       -
           def __repr__(self) -> str:

     

       154
       154
       -
               """Return a string representation of the typed object.

     

       155
       155
       -
       

     

       156
       156
       -
               Returns:

     

       157
       157
       -
                   A string representation of the typed object.

     

       158
       158
       -
               """

     

       159
       159
       -
               return f"TypedObject(type_name={self.type_name!r}, data={self.data!r})"

     

       160
       160
       -
       

     

       161
       161
       -
           def __eq__(self, other: Any) -> bool:

     

       162
       162
       -
               """Check if two typed objects are equal.

     

       163
       163
       -
       

     

       164
       164
       -
               Args:

     

       165
       165
       -
                   other: The object to compare with.

     

       166
       166
       -
       

     

       167
       167
       -
               Returns:

     

       168
       168
       -
                   True if the objects are equal, False otherwise.

     

       169
       169
       -
               """

     

       170
       170
       -
               if not isinstance(other, TypedObject):

     

       171
       171
       -
                   return False

     

       172
       172
       -
               return self.type_name == other.type_name and self.data == other.data

     

       173
       173
       -
       

     

       174
       174
       -
           def __atproto_json_encode__(self) -> Dict[str, Any]:

     

       175
       175
       -
               """Encode the typed object to a JSON-serializable format.

     

       176
       176
       -
       

     

       177
       177
       -
               Returns:

     

       178
       178
       -
                   A JSON-serializable representation of the typed object.

     

       179
       179
       -
               """

     

       180
       180
       -
               result = {"$type": self.type_name}

     

       181
       181
       -
               result.update(self.data)

     

       182
       182
       -
               return result

-82

src/atpasser/data/encoder.py

···

       1
       1
       -
       """

     

       2
       2
       -
       JSON encoder for ATProto data model.

     

       3
       3
       -
       

     

       4
       4
       -
       This module provides a JSON encoder that handles ATProto-specific data types,

     

       5
       5
       -
       including bytes, CID links, and typed objects.

     

       6
       6
       -
       """

     

       7
       7
       -
       

     

       8
       8
       -
       import base64

     

       9
       9
       -
       import json

     

       10
       10
       -
       from typing import Any, Optional

     

       11
       11
       -
       from cid import CIDv0, CIDv1

     

       12
       12
       -
       

     

       13
       13
       -
       

     

       14
       14
       -
       class JsonEncoder(json.JSONEncoder):

     

       15
       15
       -
           """A JSON encoder that supports ATProto data types.

     

       16
       16
       -
       

     

       17
       17
       -
           This encoder extends the standard JSON encoder to handle ATProto-specific

     

       18
       18
       -
           data types, including bytes, CID links, and typed objects.

     

       19
       19
       -
       

     

       20
       20
       -
           Attributes:

     

       21
       21
       -
               encoding (str): The encoding to use for string serialization.

     

       22
       22
       -
               type_processor_registry: Registry for type-specific processors.

     

       23
       23
       -
           """

     

       24
       24
       -
       

     

       25
       25
       -
           def __init__(

     

       26
       26
       -
               self,

     

       27
       27
       -
               *,

     

       28
       28
       -
               encoding: str = "utf-8",

     

       29
       29
       -
               type_processor_registry: Optional[Any] = None,

     

       30
       30
       -
               **kwargs: Any,

     

       31
       31
       -
           ) -> None:

     

       32
       32
       -
               """Initialize the JSON encoder.

     

       33
       33
       -
       

     

       34
       34
       -
               Args:

     

       35
       35
       -
                   encoding: The encoding to use for string serialization.

     

       36
       36
       -
                   type_processor_registry: Registry for type-specific processors.

     

       37
       37
       -
                   **kwargs: Additional keyword arguments to pass to the parent class.

     

       38
       38
       -
               """

     

       39
       39
       -
               super().__init__(**kwargs)

     

       40
       40
       -
               self.encoding = encoding

     

       41
       41
       -
               self.type_processor_registry = type_processor_registry

     

       42
       42
       -
       

     

       43
       43
       -
           def default(self, o: Any) -> Any:

     

       44
       44
       -
               """Convert an object to a serializable format.

     

       45
       45
       -
       

     

       46
       46
       -
               Args:

     

       47
       47
       -
                   o: The object to serialize.

     

       48
       48
       -
       

     

       49
       49
       -
               Returns:

     

       50
       50
       -
                   A serializable representation of the object.

     

       51
       51
       -
       

     

       52
       52
       -
               Raises:

     

       53
       53
       -
                   TypeError: If the object is not serializable.

     

       54
       54
       -
               """

     

       55
       55
       -
               if isinstance(o, bytes):

     

       56
       56
       -
                   # Handle bytes using RFC-4648 base64 encoding

     

       57
       57
       -
                   return {"$bytes": base64.b64encode(o).decode(self.encoding)}

     

       58
       58
       -
               elif isinstance(o, (CIDv0, CIDv1)):

     

       59
       59
       -
                   # Handle CID objects

     

       60
       60
       -
                   return {"$link": str(o)}

     

       61
       61
       -
               elif hasattr(o, "__atproto_json_encode__"):

     

       62
       62
       -
                   # Handle objects with custom ATProto encoding

     

       63
       63
       -
                   return o.__atproto_json_encode__()

     

       64
       64
       -
               elif self.type_processor_registry is not None:

     

       65
       65
       -
                   # Try to find a type processor for this object

     

       66
       66
       -
                   obj_type_name = type(o).__name__

     

       67
       67
       -
                   encoder = self.type_processor_registry.get_encoder(obj_type_name)

     

       68
       68
       -
                   if encoder is not None:

     

       69
       69
       -
                       result = encoder(o)

     

       70
       70
       -
                       # Add $type field if not already present

     

       71
       71
       -
                       if isinstance(result, dict) and "$type" not in result:

     

       72
       72
       -
                           result["$type"] = obj_type_name

     

       73
       73
       -
                       return result

     

       74
       74
       -
               elif isinstance(o, dict):

     

       75
       75
       -
                   # Handle dictionaries recursively

     

       76
       76
       -
                   return {k: self.default(v) for k, v in o.items()}

     

       77
       77
       -
               elif isinstance(o, (list, tuple)):

     

       78
       78
       -
                   # Handle lists and tuples recursively

     

       79
       79
       -
                   return [self.default(item) for item in o]

     

       80
       80
       -
               else:

     

       81
       81
       -
                   # Use the parent class for other types

     

       82
       82
       -
                   return super().default(o)

-227

src/atpasser/data/hooks.py

···

       1
       1
       -
       """

     

       2
       2
       -
       Type hook system for ATProto JSON decoder.

     

       3
       3
       -
       

     

       4
       4
       -
       This module provides a decorator-based system for registering custom type handlers

     

       5
       5
       -
       for objects with $type keys in the ATProto data model.

     

       6
       6
       -
       """

     

       7
       7
       -
       

     

       8
       8
       -
       import functools

     

       9
       9
       -
       from typing import Any, Callable, Dict, Optional, TypeVar, Union

     

       10
       10
       -
       

     

       11
       11
       -
       # Type variable for the decorated function

     

       12
       12
       -
       F = TypeVar("F", bound=Callable[..., Any])

     

       13
       13
       -
       

     

       14
       14
       -
       

     

       15
       15
       -
       class TypeHookRegistry:

     

       16
       16
       -
           """Registry for type-specific hooks in the ATProto JSON decoder.

     

       17
       17
       -
       

     

       18
       18
       -
           This class maintains a registry of type-specific hooks that can be used

     

       19
       19
       -
           to customize the decoding of objects with $type keys in the ATProto data model.

     

       20
       20
       -
       

     

       21
       21
       -
           Attributes:

     

       22
       22
       -
               _handlers: Dictionary mapping type names to handler functions.

     

       23
       23
       -
           """

     

       24
       24
       -
       

     

       25
       25
       -
           def __init__(self) -> None:

     

       26
       26
       -
               """Initialize the type hook registry."""

     

       27
       27
       -
               self._handlers: Dict[str, Callable[[Dict[str, Any]], Any]] = {}

     

       28
       28
       -
       

     

       29
       29
       -
           def register(self, type_name: str) -> Callable[[F], F]:

     

       30
       30
       -
               """Register a type handler function.

     

       31
       31
       -
       

     

       32
       32
       -
               This method can be used as a decorator to register a function as a handler

     

       33
       33
       -
               for a specific type.

     

       34
       34
       -
       

     

       35
       35
       -
               Args:

     

       36
       36
       -
                   type_name: The name of the type to handle.

     

       37
       37
       -
       

     

       38
       38
       -
               Returns:

     

       39
       39
       -
                   A decorator function that registers the decorated function as a handler.

     

       40
       40
       -
       

     

       41
       41
       -
               Example:

     

       42
       42
       -
                   >>> registry = TypeHookRegistry()

     

       43
       43
       -
                   >>>

     

       44
       44
       -
                   >>> @registry.register("app.bsky.feed.post")

     

       45
       45
       -
                   ... def handle_post(data: Dict[str, Any]) -> Any:

     

       46
       46
       -
                   ...     return Post(**data)

     

       47
       47
       -
               """

     

       48
       48
       -
       

     

       49
       49
       -
               def decorator(func: F) -> F:

     

       50
       50
       -
                   self._handlers[type_name] = func

     

       51
       51
       -
                   return func

     

       52
       52
       -
       

     

       53
       53
       -
               return decorator

     

       54
       54
       -
       

     

       55
       55
       -
           def register_handler(

     

       56
       56
       -
               self, type_name: str, handler: Callable[[Dict[str, Any]], Any]

     

       57
       57
       -
           ) -> None:

     

       58
       58
       -
               """Register a type handler function directly.

     

       59
       59
       -
       

     

       60
       60
       -
               Args:

     

       61
       61
       -
                   type_name: The name of the type to handle.

     

       62
       62
       -
                   handler: The function to call when decoding objects of this type.

     

       63
       63
       -
       

     

       64
       64
       -
               Example:

     

       65
       65
       -
                   >>> registry = TypeHookRegistry()

     

       66
       66
       -
                   >>>

     

       67
       67
       -
                   >>> def handle_post(data: Dict[str, Any]) -> Any:

     

       68
       68
       -
                   ...     return Post(**data)

     

       69
       69
       -
                   >>>

     

       70
       70
       -
                   >>> registry.register_handler("app.bsky.feed.post", handle_post)

     

       71
       71
       -
               """

     

       72
       72
       -
               self._handlers[type_name] = handler

     

       73
       73
       -
       

     

       74
       74
       -
           def unregister(self, type_name: str) -> None:

     

       75
       75
       -
               """Unregister a type handler function.

     

       76
       76
       -
       

     

       77
       77
       -
               Args:

     

       78
       78
       -
                   type_name: The name of the type to unregister.

     

       79
       79
       -
               """

     

       80
       80
       -
               if type_name in self._handlers:

     

       81
       81
       -
                   del self._handlers[type_name]

     

       82
       82
       -
       

     

       83
       83
       -
           def get_handler(self, type_name: str) -> Optional[Callable[[Dict[str, Any]], Any]]:

     

       84
       84
       -
               """Get the handler function for a specific type.

     

       85
       85
       -
       

     

       86
       86
       -
               Args:

     

       87
       87
       -
                   type_name: The name of the type to get the handler for.

     

       88
       88
       -
       

     

       89
       89
       -
               Returns:

     

       90
       90
       -
                   The handler function for the specified type, or None if no handler

     

       91
       91
       -
                   is registered.

     

       92
       92
       -
               """

     

       93
       93
       -
               return self._handlers.get(type_name)

     

       94
       94
       -
       

     

       95
       95
       -
           def has_handler(self, type_name: str) -> bool:

     

       96
       96
       -
               """Check if a handler is registered for a specific type.

     

       97
       97
       -
       

     

       98
       98
       -
               Args:

     

       99
       99
       -
                   type_name: The name of the type to check.

     

       100
       100
       -
       

     

       101
       101
       -
               Returns:

     

       102
       102
       -
                   True if a handler is registered for the specified type, False otherwise.

     

       103
       103
       -
               """

     

       104
       104
       -
               return type_name in self._handlers

     

       105
       105
       -
       

     

       106
       106
       -
           def clear(self) -> None:

     

       107
       107
       -
               """Clear all registered handlers."""

     

       108
       108
       -
               self._handlers.clear()

     

       109
       109
       -
       

     

       110
       110
       -
           def get_registered_types(self) -> set:

     

       111
       111
       -
               """Get the set of all registered type names.

     

       112
       112
       -
       

     

       113
       113
       -
               Returns:

     

       114
       114
       -
                   A set of all registered type names.

     

       115
       115
       -
               """

     

       116
       116
       -
               return set(self._handlers.keys())

     

       117
       117
       -
       

     

       118
       118
       -
       

     

       119
       119
       -
       # Global registry instance

     

       120
       120
       -
       _global_registry = TypeHookRegistry()

     

       121
       121
       -
       

     

       122
       122
       -
       

     

       123
       123
       -
       def type_handler(type_name: str) -> Callable[[F], F]:

     

       124
       124
       -
           """Register a global type handler function.

     

       125
       125
       -
       

     

       126
       126
       -
           This decorator registers a function as a global handler for a specific type

     

       127
       127
       -
           in the ATProto data model.

     

       128
       128
       -
       

     

       129
       129
       -
           Args:

     

       130
       130
       -
               type_name: The name of the type to handle.

     

       131
       131
       -
       

     

       132
       132
       -
           Returns:

     

       133
       133
       -
               A decorator function that registers the decorated function as a handler.

     

       134
       134
       -
       

     

       135
       135
       -
           Example:

     

       136
       136
       -
               >>> @type_handler("app.bsky.feed.post")

     

       137
       137
       -
               ... def handle_post(data: Dict[str, Any]) -> Any:

     

       138
       138
       -
               ...     return Post(**data)

     

       139
       139
       -
           """

     

       140
       140
       -
           return _global_registry.register(type_name)

     

       141
       141
       -
       

     

       142
       142
       -
       

     

       143
       143
       -
       def get_global_registry() -> TypeHookRegistry:

     

       144
       144
       -
           """Get the global type hook registry.

     

       145
       145
       -
       

     

       146
       146
       -
           Returns:

     

       147
       147
       -
               The global TypeHookRegistry instance.

     

       148
       148
       -
           """

     

       149
       149
       -
           return _global_registry

     

       150
       150
       -
       

     

       151
       151
       -
       

     

       152
       152
       -
       def register_type_handler(

     

       153
       153
       -
           type_name: str, handler: Callable[[Dict[str, Any]], Any]

     

       154
       154
       -
       ) -> None:

     

       155
       155
       -
           """Register a global type handler function directly.

     

       156
       156
       -
       

     

       157
       157
       -
           Args:

     

       158
       158
       -
               type_name: The name of the type to handle.

     

       159
       159
       -
               handler: The function to call when decoding objects of this type.

     

       160
       160
       -
       

     

       161
       161
       -
           Example:

     

       162
       162
       -
               >>> def handle_post(data: Dict[str, Any]) -> Any:

     

       163
       163
       -
               ...     return Post(**data)

     

       164
       164
       -
               >>>

     

       165
       165
       -
               >>> register_type_handler("app.bsky.feed.post", handle_post)

     

       166
       166
       -
           """

     

       167
       167
       -
           _global_registry.register_handler(type_name, handler)

     

       168
       168
       -
       

     

       169
       169
       -
       

     

       170
       170
       -
       def unregister_type_handler(type_name: str) -> None:

     

       171
       171
       -
           """Unregister a global type handler function.

     

       172
       172
       -
       

     

       173
       173
       -
           Args:

     

       174
       174
       -
               type_name: The name of the type to unregister.

     

       175
       175
       -
           """

     

       176
       176
       -
           _global_registry.unregister(type_name)

     

       177
       177
       -
       

     

       178
       178
       -
       

     

       179
       179
       -
       def get_type_handler(type_name: str) -> Optional[Callable[[Dict[str, Any]], Any]]:

     

       180
       180
       -
           """Get the global handler function for a specific type.

     

       181
       181
       -
       

     

       182
       182
       -
           Args:

     

       183
       183
       -
               type_name: The name of the type to get the handler for.

     

       184
       184
       -
       

     

       185
       185
       -
           Returns:

     

       186
       186
       -
               The handler function for the specified type, or None if no handler

     

       187
       187
       -
               is registered.

     

       188
       188
       -
           """

     

       189
       189
       -
           return _global_registry.get_handler(type_name)

     

       190
       190
       -
       

     

       191
       191
       -
       

     

       192
       192
       -
       def has_type_handler(type_name: str) -> bool:

     

       193
       193
       -
           """Check if a global handler is registered for a specific type.

     

       194
       194
       -
       

     

       195
       195
       -
           Args:

     

       196
       196
       -
               type_name: The name of the type to check.

     

       197
       197
       -
       

     

       198
       198
       -
           Returns:

     

       199
       199
       -
               True if a handler is registered for the specified type, False otherwise.

     

       200
       200
       -
           """

     

       201
       201
       -
           return _global_registry.has_handler(type_name)

     

       202
       202
       -
       

     

       203
       203
       -
       

     

       204
       204
       -
       def clear_type_handlers() -> None:

     

       205
       205
       -
           """Clear all globally registered handlers."""

     

       206
       206
       -
           _global_registry.clear()

     

       207
       207
       -
       

     

       208
       208
       -
       

     

       209
       209
       -
       def get_registered_types() -> set:

     

       210
       210
       -
           """Get the set of all globally registered type names.

     

       211
       211
       -
       

     

       212
       212
       -
           Returns:

     

       213
       213
       -
               A set of all registered type names.

     

       214
       214
       -
           """

     

       215
       215
       -
           return _global_registry.get_registered_types()

     

       216
       216
       -
       

     

       217
       217
       -
       

     

       218
       218
       -
       def create_registry() -> TypeHookRegistry:

     

       219
       219
       -
           """Create a new type hook registry.

     

       220
       220
       -
       

     

       221
       221
       -
           This function creates a new, independent registry that can be used

     

       222
       222
       -
           instead of the global registry.

     

       223
       223
       -
       

     

       224
       224
       -
           Returns:

     

       225
       225
       -
               A new TypeHookRegistry instance.

     

       226
       226
       -
           """

     

       227
       227
       -
           return TypeHookRegistry()

-346

src/atpasser/data/wrapper.py

···

       1
       1
       -
       """

     

       2
       2
       -
       JSON wrapper functions for ATProto data model.

     

       3
       3
       -
       

     

       4
       4
       -
       This module provides wrapper functions that mirror the standard json module

     

       5
       5
       -
       but with support for ATProto-specific data types.

     

       6
       6
       -
       """

     

       7
       7
       -
       

     

       8
       8
       -
       import json

     

       9
       9
       -
       import io

     

       10
       10
       -
       from typing import Any, Callable, Dict, Optional, TextIO, Union

     

       11
       11
       -
       from .encoder import JsonEncoder

     

       12
       12
       -
       from .decoder import JsonDecoder

     

       13
       13
       -
       from .hooks import TypeHookRegistry

     

       14
       14
       -
       from .types import TypeProcessorRegistry

     

       15
       15
       -
       

     

       16
       16
       -
       

     

       17
       17
       -
       def dump(

     

       18
       18
       -
           obj: Any,

     

       19
       19
       -
           fp: TextIO,

     

       20
       20
       -
           *,

     

       21
       21
       -
           skipkeys: bool = False,

     

       22
       22
       -
           ensure_ascii: bool = True,

     

       23
       23
       -
           check_circular: bool = True,

     

       24
       24
       -
           allow_nan: bool = True,

     

       25
       25
       -
           cls: Optional[type[JsonEncoder]] = None,

     

       26
       26
       -
           indent: Optional[Union[int, str]] = None,

     

       27
       27
       -
           separators: Optional[tuple[str, str]] = None,

     

       28
       28
       -
           default: Optional[Callable[[Any], Any]] = None,

     

       29
       29
       -
           sort_keys: bool = False,

     

       30
       30
       -
           encoding: str = "utf-8",

     

       31
       31
       -
           type_processor_registry: Optional[TypeProcessorRegistry] = None,

     

       32
       32
       -
           **kwargs: Any,

     

       33
       33
       -
       ) -> None:

     

       34
       34
       -
           """Serialize obj as a JSON formatted stream to fp.

     

       35
       35
       -
       

     

       36
       36
       -
           This function is similar to json.dump() but supports ATProto-specific

     

       37
       37
       -
           data types, including bytes, CID links, and typed objects.

     

       38
       38
       -
       

     

       39
       39
       -
           Args:

     

       40
       40
       -
               obj: The object to serialize.

     

       41
       41
       -
               fp: A file-like object with a write() method.

     

       42
       42
       -
               skipkeys: If True, dict keys that are not basic types (str, int, float,

     

       43
       43
       -
                   bool, None) will be skipped instead of raising a TypeError.

     

       44
       44
       -
               ensure_ascii: If True, the output is guaranteed to have all incoming

     

       45
       45
       -
                   non-ASCII characters escaped. If False, these characters will be

     

       46
       46
       -
                   output as-is.

     

       47
       47
       -
               check_circular: If True, circular references will be checked and

     

       48
       48
       -
                   a CircularReferenceError will be raised if one is found.

     

       49
       49
       -
               allow_nan: If True, NaN, Infinity, and -Infinity will be encoded as

     

       50
       50
       -
                   such. This behavior is not JSON specification compliant, but it

     

       51
       51
       -
                   is consistent with most JavaScript based encoders and decoders.

     

       52
       52
       -
                   Otherwise, it will raise a ValueError.

     

       53
       53
       -
               cls: A custom JSONEncoder subclass. If not specified, JsonEncoder is used.

     

       54
       54
       -
               indent: If indent is a non-negative integer or string, then JSON array

     

       55
       55
       -
                   elements and object members will be pretty-printed with that indent

     

       56
       56
       -
                   level. An indent level of 0, negative, or "" will only insert newlines.

     

       57
       57
       -
                   None (the default) selects the most compact representation.

     

       58
       58
       -
               separators: If specified, separators should be an (item_separator, key_separator)

     

       59
       59
       -
                   tuple. The default is (', ', ': ') if indent is None and (',', ': ') otherwise.

     

       60
       60
       -
                   To get the most compact JSON representation, you should specify (',', ':')

     

       61
       61
       -
                   to eliminate whitespace.

     

       62
       62
       -
               default: If specified, default should be a function that gets called for

     

       63
       63
       -
                   objects that can't otherwise be serialized. It should return a JSON

     

       64
       64
       -
                   encodable version of the object or raise a TypeError.

     

       65
       65
       -
               sort_keys: If sort_keys is True, then the output of dictionaries will be

     

       66
       66
       -
                   sorted by key.

     

       67
       67
       -
               encoding: The encoding to use for string serialization.

     

       68
       68
       -
               type_processor_registry: Registry for type-specific processors.

     

       69
       69
       -
               **kwargs: Additional keyword arguments to pass to the JSON encoder.

     

       70
       70
       -
           """

     

       71
       71
       -
           if cls is None:

     

       72
       72
       -
               cls = JsonEncoder

     

       73
       73
       -
       

     

       74
       74
       -
           # Use the global type processor registry if none is provided

     

       75
       75
       -
           if type_processor_registry is None:

     

       76
       76
       -
               from .types import get_global_processor_registry

     

       77
       77
       -
       

     

       78
       78
       -
               type_processor_registry = get_global_processor_registry()

     

       79
       79
       -
       

     

       80
       80
       -
           # Create an encoder instance with the specified encoding and type processor registry

     

       81
       81
       -
           encoder = cls(

     

       82
       82
       -
               encoding=encoding, type_processor_registry=type_processor_registry, **kwargs

     

       83
       83
       -
           )

     

       84
       84
       -
       

     

       85
       85
       -
           # Use the standard json.dump with our custom encoder

     

       86
       86
       -
           json.dump(

     

       87
       87
       -
               obj,

     

       88
       88
       -
               fp,

     

       89
       89
       -
               skipkeys=skipkeys,

     

       90
       90
       -
               ensure_ascii=ensure_ascii,

     

       91
       91
       -
               check_circular=check_circular,

     

       92
       92
       -
               allow_nan=allow_nan,

     

       93
       93
       -
               cls=cls,

     

       94
       94
       -
               indent=indent,

     

       95
       95
       -
               separators=separators,

     

       96
       96
       -
               default=default,

     

       97
       97
       -
               sort_keys=sort_keys,

     

       98
       98
       -
               **kwargs,

     

       99
       99
       -
           )

     

       100
       100
       -
       

     

       101
       101
       -
       

     

       102
       102
       -
       def dumps(

     

       103
       103
       -
           obj: Any,

     

       104
       104
       -
           *,

     

       105
       105
       -
           skipkeys: bool = False,

     

       106
       106
       -
           ensure_ascii: bool = True,

     

       107
       107
       -
           check_circular: bool = True,

     

       108
       108
       -
           allow_nan: bool = True,

     

       109
       109
       -
           cls: Optional[type[JsonEncoder]] = None,

     

       110
       110
       -
           indent: Optional[Union[int, str]] = None,

     

       111
       111
       -
           separators: Optional[tuple[str, str]] = None,

     

       112
       112
       -
           default: Optional[Callable[[Any], Any]] = None,

     

       113
       113
       -
           sort_keys: bool = False,

     

       114
       114
       -
           encoding: str = "utf-8",

     

       115
       115
       -
           type_processor_registry: Optional[TypeProcessorRegistry] = None,

     

       116
       116
       -
           **kwargs: Any,

     

       117
       117
       -
       ) -> str:

     

       118
       118
       -
           """Serialize obj to a JSON formatted string.

     

       119
       119
       -
       

     

       120
       120
       -
           This function is similar to json.dumps() but supports ATProto-specific

     

       121
       121
       -
           data types, including bytes, CID links, and typed objects.

     

       122
       122
       -
       

     

       123
       123
       -
           Args:

     

       124
       124
       -
               obj: The object to serialize.

     

       125
       125
       -
               skipkeys: If True, dict keys that are not basic types (str, int, float,

     

       126
       126
       -
                   bool, None) will be skipped instead of raising a TypeError.

     

       127
       127
       -
               ensure_ascii: If True, the output is guaranteed to have all incoming

     

       128
       128
       -
                   non-ASCII characters escaped. If False, these characters will be

     

       129
       129
       -
                   output as-is.

     

       130
       130
       -
               check_circular: If True, circular references will be checked and

     

       131
       131
       -
                   a CircularReferenceError will be raised if one is found.

     

       132
       132
       -
               allow_nan: If True, NaN, Infinity, and -Infinity will be encoded as

     

       133
       133
       -
                   such. This behavior is not JSON specification compliant, but it

     

       134
       134
       -
                   is consistent with most JavaScript based encoders and decoders.

     

       135
       135
       -
                   Otherwise, it will raise a ValueError.

     

       136
       136
       -
               cls: A custom JSONEncoder subclass. If not specified, JsonEncoder is used.

     

       137
       137
       -
               indent: If indent is a non-negative integer or string, then JSON array

     

       138
       138
       -
                   elements and object members will be pretty-printed with that indent

     

       139
       139
       -
                   level. An indent level of 0, negative, or "" will only insert newlines.

     

       140
       140
       -
                   None (the default) selects the most compact representation.

     

       141
       141
       -
               separators: If specified, separators should be an (item_separator, key_separator)

     

       142
       142
       -
                   tuple. The default is (', ', ': ') if indent is None and (',', ': ') otherwise.

     

       143
       143
       -
                   To get the most compact JSON representation, you should specify (',', ':')

     

       144
       144
       -
                   to eliminate whitespace.

     

       145
       145
       -
               default: If specified, default should be a function that gets called for

     

       146
       146
       -
                   objects that can't otherwise be serialized. It should return a JSON

     

       147
       147
       -
                   encodable version of the object or raise a TypeError.

     

       148
       148
       -
               sort_keys: If sort_keys is True, then the output of dictionaries will be

     

       149
       149
       -
                   sorted by key.

     

       150
       150
       -
               encoding: The encoding to use for string serialization.

     

       151
       151
       -
               type_processor_registry: Registry for type-specific processors.

     

       152
       152
       -
               **kwargs: Additional keyword arguments to pass to the JSON encoder.

     

       153
       153
       -
       

     

       154
       154
       -
           Returns:

     

       155
       155
       -
               A JSON formatted string.

     

       156
       156
       -
           """

     

       157
       157
       -
           if cls is None:

     

       158
       158
       -
               cls = JsonEncoder

     

       159
       159
       -
       

     

       160
       160
       -
           # Create an encoder instance with the specified encoding and type processor registry

     

       161
       161
       -
           encoder = cls(

     

       162
       162
       -
               encoding=encoding, type_processor_registry=type_processor_registry, **kwargs

     

       163
       163
       -
           )

     

       164
       164
       -
       

     

       165
       165
       -
           # Use the standard json.dumps with our custom encoder

     

       166
       166
       -
           return json.dumps(

     

       167
       167
       -
               obj,

     

       168
       168
       -
               skipkeys=skipkeys,

     

       169
       169
       -
               ensure_ascii=ensure_ascii,

     

       170
       170
       -
               check_circular=check_circular,

     

       171
       171
       -
               allow_nan=allow_nan,

     

       172
       172
       -
               cls=cls,

     

       173
       173
       -
               indent=indent,

     

       174
       174
       -
               separators=separators,

     

       175
       175
       -
               default=default,

     

       176
       176
       -
               sort_keys=sort_keys,

     

       177
       177
       -
               **kwargs,

     

       178
       178
       -
           )

     

       179
       179
       -
       

     

       180
       180
       -
       

     

       181
       181
       -
       def load(

     

       182
       182
       -
           fp: TextIO,

     

       183
       183
       -
           *,

     

       184
       184
       -
           cls: Optional[type[JsonDecoder]] = None,

     

       185
       185
       -
           object_hook: Optional[Callable[[Dict[str, Any]], Any]] = None,

     

       186
       186
       -
           parse_float: Optional[Callable[[str], Any]] = None,

     

       187
       187
       -
           parse_int: Optional[Callable[[str], Any]] = None,

     

       188
       188
       -
           parse_constant: Optional[Callable[[str], Any]] = None,

     

       189
       189
       -
           object_pairs_hook: Optional[Callable[[list[tuple[str, Any]]], Any]] = None,

     

       190
       190
       -
           type_hook_registry: Optional[TypeHookRegistry] = None,

     

       191
       191
       -
           type_processor_registry: Optional[TypeProcessorRegistry] = None,

     

       192
       192
       -
           encoding: str = "utf-8",

     

       193
       193
       -
           **kwargs: Any,

     

       194
       194
       -
       ) -> Any:

     

       195
       195
       -
           """Deserialize fp (a .read()-supporting text file or binary file containing

     

       196
       196
       -
           a JSON document) to a Python object.

     

       197
       197
       -
       

     

       198
       198
       -
           This function is similar to json.load() but supports ATProto-specific

     

       199
       199
       -
           data types, including bytes, CID links, and typed objects.

     

       200
       200
       -
       

     

       201
       201
       -
           Args:

     

       202
       202
       -
               fp: A .read()-supporting text file or binary file containing a JSON document.

     

       203
       203
       -
               cls: A custom JSONDecoder subclass. If not specified, JsonDecoder is used.

     

       204
       204
       -
               object_hook: Optional function that will be called with the result of

     

       205
       205
       -
                   every JSON object decoded and its return value will be used in place

     

       206
       206
       -
                   of the given dict.

     

       207
       207
       -
               parse_float: Optional function that will be called with the string of

     

       208
       208
       -
                   every JSON float to be decoded. By default, this is equivalent to

     

       209
       209
       -
                   float(num_str). This can be used to use another datatype or parser

     

       210
       210
       -
                   for JSON floats (e.g. decimal.Decimal).

     

       211
       211
       -
               parse_int: Optional function that will be called with the string of

     

       212
       212
       -
                   every JSON int to be decoded. By default, this is equivalent to

     

       213
       213
       -
                   int(num_str). This can be used to use another datatype or parser

     

       214
       214
       -
                   for JSON integers (e.g. float).

     

       215
       215
       -
               parse_constant: Optional function that will be called with the string of

     

       216
       216
       -
                   every JSON constant to be decoded. By default, this is equivalent to

     

       217
       217
       -
                   constant_mapping[constant_str]. This can be used to use another

     

       218
       218
       -
                   datatype or parser for JSON constants (e.g. decimal.Decimal).

     

       219
       219
       -
               object_pairs_hook: Optional function that will be called with the result

     

       220
       220
       -
                   of every JSON object decoded with an ordered list of pairs. The return

     

       221
       221
       -
                   value of object_pairs_hook will be used instead of the dict. This

     

       222
       222
       -
                   feature can be used to implement custom decoders. If object_hook is

     

       223
       223
       -
                   also defined, the object_pairs_hook takes priority.

     

       224
       224
       -
               type_hook_registry: Registry for type-specific hooks.

     

       225
       225
       -
               type_processor_registry: Registry for type-specific processors.

     

       226
       226
       -
               encoding: The encoding to use for string deserialization.

     

       227
       227
       -
               **kwargs: Additional keyword arguments to pass to the JSON decoder.

     

       228
       228
       -
       

     

       229
       229
       -
           Returns:

     

       230
       230
       -
               A Python object.

     

       231
       231
       -
           """

     

       232
       232
       -
           if cls is None:

     

       233
       233
       -
               cls = JsonDecoder

     

       234
       234
       -
       

     

       235
       235
       -
           # Use the global type hook registry if none is provided

     

       236
       236
       -
           if type_hook_registry is None and type_processor_registry is None:

     

       237
       237
       -
               from .hooks import get_global_registry

     

       238
       238
       -
       

     

       239
       239
       -
               type_hook_registry = get_global_registry()

     

       240
       240
       -
           elif type_processor_registry is not None:

     

       241
       241
       -
               # Convert the type processor registry to a hook registry

     

       242
       242
       -
               type_hook_registry = type_processor_registry.to_hook_registry()

     

       243
       243
       -
       

     

       244
       244
       -
           # Create a decoder instance with the specified parameters

     

       245
       245
       -
           decoder = cls(

     

       246
       246
       -
               object_hook=object_hook,

     

       247
       247
       -
               type_hook_registry=type_hook_registry,

     

       248
       248
       -
               encoding=encoding,

     

       249
       249
       -
               **kwargs,

     

       250
       250
       -
           )

     

       251
       251
       -
       

     

       252
       252
       -
           # Use the standard json.load with our custom decoder

     

       253
       253
       -
           return json.load(

     

       254
       254
       -
               fp,

     

       255
       255
       -
               cls=cls,

     

       256
       256
       -
               object_hook=object_hook,

     

       257
       257
       -
               parse_float=parse_float,

     

       258
       258
       -
               parse_int=parse_int,

     

       259
       259
       -
               parse_constant=parse_constant,

     

       260
       260
       -
               object_pairs_hook=object_pairs_hook,

     

       261
       261
       -
               **kwargs,

     

       262
       262
       -
           )

     

       263
       263
       -
       

     

       264
       264
       -
       

     

       265
       265
       -
       def loads(

     

       266
       266
       -
           s: Union[str, bytes],

     

       267
       267
       -
           *,

     

       268
       268
       -
           cls: Optional[type[JsonDecoder]] = None,

     

       269
       269
       -
           object_hook: Optional[Callable[[Dict[str, Any]], Any]] = None,

     

       270
       270
       -
           parse_float: Optional[Callable[[str], Any]] = None,

     

       271
       271
       -
           parse_int: Optional[Callable[[str], Any]] = None,

     

       272
       272
       -
           parse_constant: Optional[Callable[[str], Any]] = None,

     

       273
       273
       -
           object_pairs_hook: Optional[Callable[[list[tuple[str, Any]]], Any]] = None,

     

       274
       274
       -
           type_hook_registry: Optional[TypeHookRegistry] = None,

     

       275
       275
       -
           type_processor_registry: Optional[TypeProcessorRegistry] = None,

     

       276
       276
       -
           encoding: str = "utf-8",

     

       277
       277
       -
           **kwargs: Any,

     

       278
       278
       -
       ) -> Any:

     

       279
       279
       -
           """Deserialize s (a str, bytes or bytearray instance containing a JSON document)

     

       280
       280
       -
           to a Python object.

     

       281
       281
       -
       

     

       282
       282
       -
           This function is similar to json.loads() but supports ATProto-specific

     

       283
       283
       -
           data types, including bytes, CID links, and typed objects.

     

       284
       284
       -
       

     

       285
       285
       -
           Args:

     

       286
       286
       -
               s: A str, bytes or bytearray instance containing a JSON document.

     

       287
       287
       -
               cls: A custom JSONDecoder subclass. If not specified, JsonDecoder is used.

     

       288
       288
       -
               object_hook: Optional function that will be called with the result of

     

       289
       289
       -
                   every JSON object decoded and its return value will be used in place

     

       290
       290
       -
                   of the given dict.

     

       291
       291
       -
               parse_float: Optional function that will be called with the string of

     

       292
       292
       -
                   every JSON float to be decoded. By default, this is equivalent to

     

       293
       293
       -
                   float(num_str). This can be used to use another datatype or parser

     

       294
       294
       -
                   for JSON floats (e.g. decimal.Decimal).

     

       295
       295
       -
               parse_int: Optional function that will be called with the string of

     

       296
       296
       -
                   every JSON int to be decoded. By default, this is equivalent to

     

       297
       297
       -
                   int(num_str). This can be used to use another datatype or parser

     

       298
       298
       -
                   for JSON integers (e.g. float).

     

       299
       299
       -
               parse_constant: Optional function that will be called with the string of

     

       300
       300
       -
                   every JSON constant to be decoded. By default, this is equivalent to

     

       301
       301
       -
                   constant_mapping[constant_str]. This can be used to use another

     

       302
       302
       -
                   datatype or parser for JSON constants (e.g. decimal.Decimal).

     

       303
       303
       -
               object_pairs_hook: Optional function that will be called with the result

     

       304
       304
       -
                   of every JSON object decoded with an ordered list of pairs. The return

     

       305
       305
       -
                   value of object_pairs_hook will be used instead of the dict. This

     

       306
       306
       -
                   feature can be used to implement custom decoders. If object_hook is

     

       307
       307
       -
                   also defined, the object_pairs_hook takes priority.

     

       308
       308
       -
               type_hook_registry: Registry for type-specific hooks.

     

       309
       309
       -
               type_processor_registry: Registry for type-specific processors.

     

       310
       310
       -
               encoding: The encoding to use for string deserialization.

     

       311
       311
       -
               **kwargs: Additional keyword arguments to pass to the JSON decoder.

     

       312
       312
       -
       

     

       313
       313
       -
           Returns:

     

       314
       314
       -
               A Python object.

     

       315
       315
       -
           """

     

       316
       316
       -
           if cls is None:

     

       317
       317
       -
               cls = JsonDecoder

     

       318
       318
       -
       

     

       319
       319
       -
           # Use the global type hook registry if none is provided

     

       320
       320
       -
           if type_hook_registry is None and type_processor_registry is None:

     

       321
       321
       -
               from .hooks import get_global_registry

     

       322
       322
       -
       

     

       323
       323
       -
               type_hook_registry = get_global_registry()

     

       324
       324
       -
           elif type_processor_registry is not None:

     

       325
       325
       -
               # Convert the type processor registry to a hook registry

     

       326
       326
       -
               type_hook_registry = type_processor_registry.to_hook_registry()

     

       327
       327
       -
       

     

       328
       328
       -
           # Create a decoder instance with the specified parameters

     

       329
       329
       -
           decoder = cls(

     

       330
       330
       -
               object_hook=object_hook,

     

       331
       331
       -
               type_hook_registry=type_hook_registry,

     

       332
       332
       -
               encoding=encoding,

     

       333
       333
       -
               **kwargs,

     

       334
       334
       -
           )

     

       335
       335
       -
       

     

       336
       336
       -
           # Use the standard json.loads with our custom decoder

     

       337
       337
       -
           return json.loads(

     

       338
       338
       -
               s,

     

       339
       339
       -
               cls=cls,

     

       340
       340
       -
               object_hook=object_hook,

     

       341
       341
       -
               parse_float=parse_float,

     

       342
       342
       -
               parse_int=parse_int,

     

       343
       343
       -
               parse_constant=parse_constant,

     

       344
       344
       -
               object_pairs_hook=object_pairs_hook,

     

       345
       345
       -
               **kwargs,

     

       346
       346
       -
           )

+6 -1

.gitignore

···

       213
       213
        
       __marimo__/

     

       214
       214
        
       

     

       215
       215
        
       # Streamlit

     

       216
       216
       -
       .streamlit/secrets.toml
     

       216
       216
       +
       .streamlit/secrets.toml

     

       217
       217
       +
       

     

       218
       218
       +
       #####

     

       219
       219
       +
       

     

       220
       220
       +
       # Added by DWN - temp dir

     

       221
       221
       +
       tmp/

+10 -2

README.md

···

       1
       1
       -
       # ATPasser ╬<!

     

       1
       1
       +
       # ATPasser!

     

       2
       2
        
       

     

       3
       3
        
       A simple library for the [Authenticated Transfer Protocol](https://atproto.com/specs/atp) (AT Protocol or atproto for short).

     

       4
       4
        
       

     
···

       6
       6
        
       

     

       7
       7
        
       ---

     

       8
       8
        
       

     

       9
       9
       -
       [See the roadmap](docs/roadmap.md)

     

       9
       9
       +
       ## Other ATProto libraries

     

       10
       10
       +
       

     

       11
       11
       +
       [There's an ATProto SDK already (and used by lots of projects) by MarshalX,](https://github.com/MarshalX/atproto) and why do this exists?

     

       12
       12
       +
       

     

       13
       13
       +
       The first reason is that I'm recovering the now-closed [Tietiequan](https://tangled.org/@dwn.dwnfonts.cc/bluesky-circle) app and found that some API has changed so I have to rewrite it via vanilla JS.

     

       14
       14
       +
       

     

       15
       15
       +
       The second reason is that I'm a newbie in ATProto, wanting to know how ATProto is, and how this can be represented in Python.

     

       16
       16
       +
       

     

       17
       17
       +
       The architecture will be small, only containing the data model and the client.

     

       10
       18
        
       

     

       11
       19
        
       ---

     

       12
       20

-16

src/atpasser/blob/__init__.py

···

       1
       1
       -
       import cid

     

       2
       2
       -
       import multihash, hashlib

     

       3
       3
       -
       

     

       4
       4
       -
       

     

       5
       5
       -
       def generateCID(file):

     

       6
       6
       -
           hasher = hashlib.new("sha-256")

     

       7
       7
       -
           while True:

     

       8
       8
       -
               chunk = file.read(8192)

     

       9
       9
       -
               if not chunk:

     

       10
       10
       -
                   break

     

       11
       11
       -
               hasher.update(chunk)

     

       12
       12
       -
       

     

       13
       13
       -
           digest = hasher.digest

     

       14
       14
       -
           mh = multihash.encode(digest, "sha-256")

     

       15
       15
       -
       

     

       16
       16
       -
           return cid.CIDv1(codec="raw", multihash=mh)

-76

src/atpasser/data/_data.py

···

       1
       1
       -
       import base64

     

       2
       2
       -
       from cid import CIDv0, CIDv1, cid, make_cid

     

       3
       3
       -
       import json

     

       4
       4
       -
       

     

       5
       5
       -
       

     

       6
       6
       -
       class Data:

     

       7
       7
       -
           """

     

       8
       8
       -
           A class representing data with "$type" key.

     

       9
       9
       -
       

     

       10
       10
       -
           Attributes:

     

       11
       11
       -
               type (str): The type of the data.

     

       12
       12
       -
               json (str): Original object in JSON format.

     

       13
       13
       -
           """

     

       14
       14
       -
       

     

       15
       15
       -
           def __init__(self, dataType: str, json: str = "{}") -> None:

     

       16
       16
       -
               """

     

       17
       17
       -
               Initalizes data object.

     

       18
       18
       -
       

     

       19
       19
       -
               Parameters:

     

       20
       20
       -
                   type (str): The type of the data.

     

       21
       21
       -
                   json (str): Original object in JSON format.

     

       22
       22
       -
               """

     

       23
       23
       -
               self.type = dataType

     

       24
       24
       -
               self.json = json

     

       25
       25
       -
       

     

       26
       26
       -
           def data(self):

     

       27
       27
       -
               """

     

       28
       28
       -
               Loads data as a Python-friendly format.

     

       29
       29
       -
       

     

       30
       30
       -
               Returns:

     

       31
       31
       -
                   dict: Converted data from JSON object.

     

       32
       32
       -
               """

     

       33
       33
       -
               return json.loads(self.json, object_hook=dataHook)

     

       34
       34
       -
       

     

       35
       35
       -
       

     

       36
       36
       -
       def dataHook(data: dict):

     

       37
       37
       -
           """

     

       38
       38
       -
           Treated as `JSONDecoder`'s `object_hook`

     

       39
       39
       -
       

     

       40
       40
       -
           Parameters:

     

       41
       41
       -
               data: data in format that `JSONDecoder` like ;)

     

       42
       42
       -
           """

     

       43
       43
       -
           if "$bytes" in data:

     

       44
       44
       -
               return base64.b64decode(data["$bytes"])

     

       45
       45
       -
           elif "$link" in data:

     

       46
       46
       -
               return make_cid(data["$link"])

     

       47
       47
       -
           elif "$type" in data:

     

       48
       48
       -
               dataType = data["$type"]

     

       49
       49
       -
               del data["$type"]

     

       50
       50
       -
               return Data(dataType, json.dumps(data))

     

       51
       51
       -
           else:

     

       52
       52
       -
               return data

     

       53
       53
       -
       

     

       54
       54
       -
       

     

       55
       55
       -
       def _convertDataToFakeJSON(data):

     

       56
       56
       -
           if isinstance(data, bytes):

     

       57
       57
       -
               return {"$bytes": base64.b64encode(data)}

     

       58
       58
       -
           elif isinstance(data, (CIDv0, CIDv1)):

     

       59
       59
       -
               return {"link": data.encode()}

     

       60
       60
       -
           elif isinstance(data, dict):

     

       61
       61
       -
               for item in data:

     

       62
       62
       -
                   data[item] = _convertDataToFakeJSON(data[item])

     

       63
       63
       -
           elif isinstance(data, (tuple, list, set)):

     

       64
       64
       -
               return [_convertDataToFakeJSON(item) for item in data]

     

       65
       65
       -
           else:

     

       66
       66
       -
               return data

     

       67
       67
       -
       

     

       68
       68
       -
       

     

       69
       69
       -
       class DataEncoder(json.JSONEncoder):

     

       70
       70
       -
           """

     

       71
       71
       -
           A superset of `JSONEncoder` to support ATProto data.

     

       72
       72
       -
           """

     

       73
       73
       -
       

     

       74
       74
       -
           def default(self, o):

     

       75
       75
       -
               result = _convertDataToFakeJSON(o)

     

       76
       76
       -
               return super().default(result)

-61

src/atpasser/data/_wrapper.py

···

       1
       1
       -
       from json import loads

     

       2
       2
       -
       from typing import Callable, Any

     

       3
       3
       -
       from ._data import *

     

       4
       4
       -
       import functools

     

       5
       5
       -
       

     

       6
       6
       -
       # Pyright did the whole job. Thank it.

     

       7
       7
       -
       

     

       8
       8
       -
       

     

       9
       9
       -
       class DataDecoder(json.JSONDecoder):

     

       10
       10
       -
           """

     

       11
       11
       -
           A superset of `JSONDecoder` to support ATProto data.

     

       12
       12
       -
           """

     

       13
       13
       -
       

     

       14
       14
       -
           def __init__(

     

       15
       15
       -
               self,

     

       16
       16
       -
               *,

     

       17
       17
       -
               object_hook: Callable[[dict[str, Any]], Any] | None = dataHook,

     

       18
       18
       -
               parse_float: Callable[[str], Any] | None = None,

     

       19
       19
       -
               parse_int: Callable[[str], Any] | None = None,

     

       20
       20
       -
               parse_constant: Callable[[str], Any] | None = None,

     

       21
       21
       -
               strict: bool = True,

     

       22
       22
       -
               object_pairs_hook: Callable[[list[tuple[str, Any]]], Any] | None = None,

     

       23
       23
       -
           ) -> None:

     

       24
       24
       -
               super().__init__(

     

       25
       25
       -
                   object_hook=object_hook,

     

       26
       26
       -
                   parse_float=parse_float,

     

       27
       27
       -
                   parse_int=parse_int,

     

       28
       28
       -
                   parse_constant=parse_constant,

     

       29
       29
       -
                   strict=strict,

     

       30
       30
       -
                   object_pairs_hook=object_pairs_hook,

     

       31
       31
       -
               )

     

       32
       32
       -
       

     

       33
       33
       -
       

     

       34
       34
       -
       # Screw it. I have to make 4 `json`-like functions.

     

       35
       35
       -
       

     

       36
       36
       -
       

     

       37
       37
       -
       def _dataDecoratorForDump(func):

     

       38
       38
       -
           @functools.wraps(func)

     

       39
       39
       -
           def wrapper(obj, *args, **kwargs):

     

       40
       40
       -
               kwargs.setdefault("cls", DataEncoder)

     

       41
       41
       -
               return func(obj, *args, **kwargs)

     

       42
       42
       -
       

     

       43
       43
       -
           return wrapper

     

       44
       44
       -
       

     

       45
       45
       -
       

     

       46
       46
       -
       def _dataDecoratorForLoad(func):

     

       47
       47
       -
           @functools.wraps(func)

     

       48
       48
       -
           def wrapper(obj, *args, **kwargs):

     

       49
       49
       -
               kwargs.setdefault("cls", DataDecoder)

     

       50
       50
       -
               return func(obj, *args, **kwargs)

     

       51
       51
       -
       

     

       52
       52
       -
           return wrapper

     

       53
       53
       -
       

     

       54
       54
       -
       

     

       55
       55
       -
       dump = _dataDecoratorForDump(json.dump)

     

       56
       56
       -
       dumps = _dataDecoratorForDump(json.dumps)

     

       57
       57
       -
       load = _dataDecoratorForLoad(json.load)

     

       58
       58
       -
       loads = _dataDecoratorForLoad(json.loads)

     

       59
       59
       -
       """

     

       60
       60
       -
       Wrapper of the JSON functions to support ATProto data.

     

       61
       61
       -
       """

-137

src/atpasser/data/cbor.py

···

       1
       1
       -
       from datetime import tzinfo

     

       2
       2
       -
       import typing

     

       3
       3
       -
       import cbor2

     

       4
       4
       -
       import cid

     

       5
       5
       -
       

     

       6
       6
       -
       from .data import dataHook, Data

     

       7
       7
       -
       

     

       8
       8
       -
       

     

       9
       9
       -
       def tagHook(decoder: cbor2.CBORDecoder, tag: cbor2.CBORTag, shareable_index=None):

     

       10
       10
       -
           """

     

       11
       11
       -
           A simple tag hook for CID support.

     

       12
       12
       -
           """

     

       13
       13
       -
           return cid.from_bytes(tag.value) if tag.tag == 42 else tag

     

       14
       14
       -
       

     

       15
       15
       -
       

     

       16
       16
       -
       class CBOREncoder(cbor2.CBOREncoder):

     

       17
       17
       -
           """

     

       18
       18
       -
           Wrapper of cbor2.CBOREncoder.

     

       19
       19
       -
           """

     

       20
       20
       -
       

     

       21
       21
       -
           def __init__(

     

       22
       22
       -
               self,

     

       23
       23
       -
               fp: typing.IO[bytes],

     

       24
       24
       -
               datetime_as_timestamp: bool = False,

     

       25
       25
       -
               timezone: tzinfo | None = None,

     

       26
       26
       -
               value_sharing: bool = False,

     

       27
       27
       -
               default: (

     

       28
       28
       -
                   typing.Callable[[cbor2.CBOREncoder, typing.Any], typing.Any] | None

     

       29
       29
       -
               ) = None,

     

       30
       30
       -
               canonical: bool = False,

     

       31
       31
       -
               date_as_datetime: bool = False,

     

       32
       32
       -
               string_referencing: bool = False,

     

       33
       33
       -
               indefinite_containers: bool = False,

     

       34
       34
       -
           ):

     

       35
       35
       -
               super().__init__(

     

       36
       36
       -
                   fp,

     

       37
       37
       -
                   datetime_as_timestamp,

     

       38
       38
       -
                   timezone,

     

       39
       39
       -
                   value_sharing,

     

       40
       40
       -
                   default,

     

       41
       41
       -
                   canonical,

     

       42
       42
       -
                   date_as_datetime,

     

       43
       43
       -
                   string_referencing,

     

       44
       44
       -
                   indefinite_containers,

     

       45
       45
       -
               )

     

       46
       46
       -
       

     

       47
       47
       -
           @cbor2.shareable_encoder

     

       48
       48
       -
           def cidOrDataEncoder(self: cbor2.CBOREncoder, value: cid.CIDv0 | cid.CIDv1 | Data):

     

       49
       49
       -
               """

     

       50
       50
       -
               Encode CID or Data to CBOR Tag.

     

       51
       51
       -
               """

     

       52
       52
       -
               if isinstance(value, (cid.CIDv0, cid.CIDv1)):

     

       53
       53
       -
                   self.encode(cbor2.CBORTag(42, value.encode()))

     

       54
       54
       -
               elif isinstance(value, Data):

     

       55
       55
       -
                   self.encode(value.data())

     

       56
       56
       -
       

     

       57
       57
       -
       

     

       58
       58
       -
       def _cborObjectHook(decoder: cbor2.CBORDecoder, value):

     

       59
       59
       -
           return dataHook(value)

     

       60
       60
       -
       

     

       61
       61
       -
       

     

       62
       62
       -
       class CBORDecoder(cbor2.CBORDecoder):

     

       63
       63
       -
           """

     

       64
       64
       -
           Wrapper of cbor2.CBORDecoder.

     

       65
       65
       -
           """

     

       66
       66
       -
       

     

       67
       67
       -
           def __init__(

     

       68
       68
       -
               self,

     

       69
       69
       -
               fp: typing.IO[bytes],

     

       70
       70
       -
               tag_hook: (

     

       71
       71
       -
                   typing.Callable[[cbor2.CBORDecoder, cbor2.CBORTag], typing.Any] | None

     

       72
       72
       -
               ) = tagHook,

     

       73
       73
       -
               object_hook: (

     

       74
       74
       -
                   typing.Callable[

     

       75
       75
       -
                       [cbor2.CBORDecoder, dict[typing.Any, typing.Any]], typing.Any

     

       76
       76
       -
                   ]

     

       77
       77
       -
                   | None

     

       78
       78
       -
               ) = _cborObjectHook,

     

       79
       79
       -
               str_errors: typing.Literal["strict", "error", "replace"] = "strict",

     

       80
       80
       -
           ):

     

       81
       81
       -
               super().__init__(fp, tag_hook, object_hook, str_errors)

     

       82
       82
       -
       

     

       83
       83
       -
       

     

       84
       84
       -
       # Make things for CBOR again.

     

       85
       85
       -
       

     

       86
       86
       -
       from io import BytesIO

     

       87
       87
       -
       

     

       88
       88
       -
       

     

       89
       89
       -
       def dumps(

     

       90
       90
       -
           obj: object,

     

       91
       91
       -
           datetime_as_timestamp: bool = False,

     

       92
       92
       -
           timezone: tzinfo | None = None,

     

       93
       93
       -
           value_sharing: bool = False,

     

       94
       94
       -
           default: typing.Callable[[cbor2.CBOREncoder, typing.Any], typing.Any] | None = None,

     

       95
       95
       -
           canonical: bool = False,

     

       96
       96
       -
           date_as_datetime: bool = False,

     

       97
       97
       -
           string_referencing: bool = False,

     

       98
       98
       -
           indefinite_containers: bool = False,

     

       99
       99
       -
       ) -> bytes:

     

       100
       100
       -
           with BytesIO() as fp:

     

       101
       101
       -
               CBOREncoder(

     

       102
       102
       -
                   fp,

     

       103
       103
       -
                   datetime_as_timestamp=datetime_as_timestamp,

     

       104
       104
       -
                   timezone=timezone,

     

       105
       105
       -
                   value_sharing=value_sharing,

     

       106
       106
       -
                   default=default,

     

       107
       107
       -
                   canonical=canonical,

     

       108
       108
       -
                   date_as_datetime=date_as_datetime,

     

       109
       109
       -
                   string_referencing=string_referencing,

     

       110
       110
       -
                   indefinite_containers=indefinite_containers,

     

       111
       111
       -
               ).encode(obj)

     

       112
       112
       -
               return fp.getvalue()

     

       113
       113
       -
       

     

       114
       114
       -
       

     

       115
       115
       -
       def dump(

     

       116
       116
       -
           obj: object,

     

       117
       117
       -
           fp: typing.IO[bytes],

     

       118
       118
       -
           datetime_as_timestamp: bool = False,

     

       119
       119
       -
           timezone: tzinfo | None = None,

     

       120
       120
       -
           value_sharing: bool = False,

     

       121
       121
       -
           default: typing.Callable[[cbor2.CBOREncoder, typing.Any], typing.Any] | None = None,

     

       122
       122
       -
           canonical: bool = False,

     

       123
       123
       -
           date_as_datetime: bool = False,

     

       124
       124
       -
           string_referencing: bool = False,

     

       125
       125
       -
           indefinite_containers: bool = False,

     

       126
       126
       -
       ) -> None:

     

       127
       127
       -
           CBOREncoder(

     

       128
       128
       -
               fp,

     

       129
       129
       -
               datetime_as_timestamp=datetime_as_timestamp,

     

       130
       130
       -
               timezone=timezone,

     

       131
       131
       -
               value_sharing=value_sharing,

     

       132
       132
       -
               default=default,

     

       133
       133
       -
               canonical=canonical,

     

       134
       134
       -
               date_as_datetime=date_as_datetime,

     

       135
       135
       -
               string_referencing=string_referencing,

     

       136
       136
       -
               indefinite_containers=indefinite_containers,

     

       137
       137
       -
           ).encode(obj)

-179

tests/_strings.py

···

       1
       1
       -
       from atpasser import did, handle, nsid, rKey, uri

     

       2
       2
       -
       

     

       3
       3
       -
       

     

       4
       4
       -
       testStrings, testMethods = {}, {}

     

       5
       5
       -
       

     

       6
       6
       -
       

     

       7
       7
       -
       testStrings[

     

       8
       8
       -
           "did"

     

       9
       9
       -
       

     

       10
       10
       -
       ] = """did:plc:z72i7hdynmk6r22z27h6tvur

     

       11
       11
       -
       

     

       12
       12
       -
       did:web:blueskyweb.xyz

     

       13
       13
       -
       

     

       14
       14
       -
       did:method:val:two

     

       15
       15
       -
       

     

       16
       16
       -
       did:m:v

     

       17
       17
       -
       

     

       18
       18
       -
       did:method::::val

     

       19
       19
       -
       

     

       20
       20
       -
       did:method:-:_:.

     

       21
       21
       -
       

     

       22
       22
       -
       did:key:zQ3shZc2QzApp2oymGvQbzP8eKheVshBHbU4ZYjeXqwSKEn6N

     

       23
       23
       -
       

     

       24
       24
       -
       did:METHOD:val

     

       25
       25
       -
       

     

       26
       26
       -
       did:m123:val

     

       27
       27
       -
       

     

       28
       28
       -
       DID:method:val

     

       29
       29
       -
       did:method:

     

       30
       30
       -
       

     

       31
       31
       -
       did:method:val/two

     

       32
       32
       -
       

     

       33
       33
       -
       did:method:val?two

     

       34
       34
       -
       

     

       35
       35
       -
       did:method:val#two"""

     

       36
       36
       -
       

     

       37
       37
       -
       testMethods["did"] = did.DID

     

       38
       38
       -
       

     

       39
       39
       -
       

     

       40
       40
       -
       testStrings[

     

       41
       41
       -
           "handle"

     

       42
       42
       -
       

     

       43
       43
       -
       ] = """jay.bsky.social

     

       44
       44
       -
       

     

       45
       45
       -
       8.cn

     

       46
       46
       -
       

     

       47
       47
       -
       name.t--t

     

       48
       48
       -
       

     

       49
       49
       -
       XX.LCS.MIT.EDU

     

       50
       50
       -
       a.co

     

       51
       51
       -
       

     

       52
       52
       -
       xn--notarealidn.com

     

       53
       53
       -
       

     

       54
       54
       -
       xn--fiqa61au8b7zsevnm8ak20mc4a87e.xn--fiqs8s

     

       55
       55
       -
       

     

       56
       56
       -
       xn--ls8h.test

     

       57
       57
       -
       example.t

     

       58
       58
       -
       

     

       59
       59
       -
       jo@hn.test

     

       60
       60
       -
       

     

       61
       61
       -
       💩.tes

     

       62
       62
       -
       t

     

       63
       63
       -
       john..test

     

       64
       64
       -
       

     

       65
       65
       -
       xn--bcher-.tld

     

       66
       66
       -
       

     

       67
       67
       -
       john.0

     

       68
       68
       -
       

     

       69
       69
       -
       cn.8

     

       70
       70
       -
       

     

       71
       71
       -
       www.masełkowski.pl.com

     

       72
       72
       -
       

     

       73
       73
       -
       org

     

       74
       74
       -
       

     

       75
       75
       -
       name.org.

     

       76
       76
       -
       

     

       77
       77
       -
       2gzyxa5ihm7nsggfxnu52rck2vv4rvmdlkiu3zzui5du4xyclen53wid.onion

     

       78
       78
       -
       laptop.local

     

       79
       79
       -
       

     

       80
       80
       -
       blah.arpa"""

     

       81
       81
       -
       

     

       82
       82
       -
       testMethods["handle"] = handle.Handle

     

       83
       83
       -
       

     

       84
       84
       -
       

     

       85
       85
       -
       testStrings[

     

       86
       86
       -
           "nsid"

     

       87
       87
       -
       

     

       88
       88
       -
       ] = """com.example.fooBar

     

       89
       89
       -
       

     

       90
       90
       -
       net.users.bob.ping

     

       91
       91
       -
       

     

       92
       92
       -
       a-0.b-1.c

     

       93
       93
       -
       

     

       94
       94
       -
       a.b.c

     

       95
       95
       -
       

     

       96
       96
       -
       com.example.fooBarV2

     

       97
       97
       -
       

     

       98
       98
       -
       cn.8.lex.stuff

     

       99
       99
       -
       

     

       100
       100
       -
       com.exa💩ple.thin

     

       101
       101
       -
       com.example

     

       102
       102
       -
       

     

       103
       103
       -
       com.example.3"""

     

       104
       104
       -
       

     

       105
       105
       -
       testMethods["nsid"] = nsid.NSID

     

       106
       106
       -
       

     

       107
       107
       -
       

     

       108
       108
       -
       testStrings[

     

       109
       109
       -
       

     

       110
       110
       -
           "rkey"

     

       111
       111
       -
       

     

       112
       112
       -
       ] = """3jui7kd54zh2y

     

       113
       113
       -
       self

     

       114
       114
       -
       example.com

     

       115
       115
       -
       

     

       116
       116
       -
       ~1.2-3_

     

       117
       117
       -
       

     

       118
       118
       -
       dHJ1ZQ

     

       119
       119
       -
       pre:fix

     

       120
       120
       -
       

     

       121
       121
       -
       _

     

       122
       122
       -
       

     

       123
       123
       -
       alpha/beta

     

       124
       124
       -
       .

     

       125
       125
       -
       ..

     

       126
       126
       -
       

     

       127
       127
       -
       #extra

     

       128
       128
       -
       

     

       129
       129
       -
       @handle

     

       130
       130
       -
       

     

       131
       131
       -
       any space

     

       132
       132
       -
       

     

       133
       133
       -
       any+space

     

       134
       134
       -
       

     

       135
       135
       -
       number[3]

     

       136
       136
       -
       

     

       137
       137
       -
       number(3)

     

       138
       138
       -
       

     

       139
       139
       -
       "quote"

     

       140
       140
       -
       

     

       141
       141
       -
       dHJ1ZQ=="""

     

       142
       142
       -
       

     

       143
       143
       -
       testMethods["rkey"] = rKey.RKey

     

       144
       144
       -
       

     

       145
       145
       -
       

     

       146
       146
       -
       testStrings[

     

       147
       147
       -
           "uri"

     

       148
       148
       -
       

     

       149
       149
       -
       ] = """at://foo.com/com.example.foo/123

     

       150
       150
       -
       

     

       151
       151
       -
       at://foo.com/example/123

     

       152
       152
       -
       

     

       153
       153
       -
       at://computer

     

       154
       154
       -
       

     

       155
       155
       -
       at://example.com:3000

     

       156
       156
       -
       

     

       157
       157
       -
       at://foo.com/

     

       158
       158
       -
       

     

       159
       159
       -
       at://user:pass@foo.com"""

     

       160
       160
       -
       

     

       161
       161
       -
       testMethods["uri"] = uri.URI

     

       162
       162
       -
       

     

       163
       163
       -
       

     

       164
       164
       -
       for item in testMethods:

     

       165
       165
       -
       

     

       166
       166
       -
           print(f"START TEST {item}")

     

       167
       167
       -
       

     

       168
       168
       -
           for value in testStrings[item].splitlines():

     

       169
       169
       -
       

     

       170
       170
       -
               print(f"Value: {value}")

     

       171
       171
       -
       

     

       172
       172
       -
               try:

     

       173
       173
       -
       

     

       174
       174
       -
                   print(f"str(): {str(testMethods[item](value))}")

     

       175
       175
       -
       

     

       176
       176
       -
               except Exception as e:

     

       177
       177
       -
       

     

       178
       178
       -
                   print(f"× {e}")

     

       179
       179
       -

pyproject.toml

···

       14
       14
        
           "jsonpath-ng (>=1.7.0,<2.0.0)",    # for URI fragment support

     

       15
       15
        
           "cryptography (>=45.0.7,<46.0.0)", # just keep it

     

       16
       16
        
           "langcodes (>=3.5.0,<4.0.0)",      # language codes support

     

       17
       17
       +
           "pydantic (>=2.11.9,<3.0.0)",

     

       17
       18
        
       ]

     

       18
       19
        
       license = "MIT OR Apache-2.0"

     

       19
       20
        
       license-files = ["LICEN[CS]E.*"]

+205

ARCHITECTURE_OVERVIEW.md

···

       1
       1
       +
       # ATProto Data 和 Lexicon 模块架构总览

     

       2
       2
       +
       

     

       3
       3
       +
       ## 项目概述

     

       4
       4
       +
       

     

       5
       5
       +
       本项目为 ATProto (Authenticated Transfer Protocol) 提供 Python 实现，专注于数据模型和 Lexicon 定义的处理。基于现有的 URI 模块架构模式，提供类型安全的数据验证、序列化和 Lexicon 解析功能。

     

       6
       6
       +
       

     

       7
       7
       +
       ## 整体架构设计

     

       8
       8
       +
       

     

       9
       9
       +
       ### 1. 系统架构图

     

       10
       10
       +
       

     

       11
       11
       +
       ```mermaid

     

       12
       12
       +
       graph TB

     

       13
       13
       +
           subgraph "ATProto 核心模块"

     

       14
       14
       +
               URI[URI 模块]

     

       15
       15
       +
               Data[Data 模块]

     

       16
       16
       +
               Lexicon[Lexicon 模块]

     

       17
       17
       +
           end

     

       18
       18
       +
           

     

       19
       19
       +
           subgraph "外部依赖"

     

       20
       20
       +
               Pydantic[Pydantic]

     

       21
       21
       +
               CBOR[cbor2]

     

       22
       22
       +
               CID[py-cid]

     

       23
       23
       +
           end

     

       24
       24
       +
           

     

       25
       25
       +
           subgraph "数据流"

     

       26
       26
       +
               LexiconJSON[Lexicon JSON 文件]

     

       27
       27
       +
               RawData[原始数据]

     

       28
       28
       +
           end

     

       29
       29
       +
           

     

       30
       30
       +
           LexiconJSON --> Lexicon

     

       31
       31
       +
           Lexicon --> Data

     

       32
       32
       +
           RawData --> Data

     

       33
       33
       +
           Data --> Serialized[序列化数据]

     

       34
       34
       +
           

     

       35
       35
       +
           URI --> Data

     

       36
       36
       +
           URI --> Lexicon

     

       37
       37
       +
           

     

       38
       38
       +
           Pydantic --> Data

     

       39
       39
       +
           Pydantic --> Lexicon

     

       40
       40
       +
           CBOR --> Data

     

       41
       41
       +
           CID --> Data

     

       42
       42
       +
       ```

     

       43
       43
       +
       

     

       44
       44
       +
       ### 2. 模块职责划分

     

       45
       45
       +
       

     

       46
       46
       +
       #### 2.1 Data 模块 (`src/atpasser/data`)

     

       47
       47
       +
       - **数据序列化**: JSON 和 DAG-CBOR 格式的序列化/反序列化

     

       48
       48
       +
       - **数据验证**: 类型验证、格式验证、约束验证

     

       49
       49
       +
       - **特殊类型处理**: CID 链接、Blob 引用、日期时间格式等

     

       50
       50
       +
       - **错误处理**: 详细的验证错误和序列化错误

     

       51
       51
       +
       

     

       52
       52
       +
       #### 2.2 Lexicon 模块 (`src/atpasser/lexicon`)

     

       53
       53
       +
       - **定义解析**: 解析 Lexicon JSON 定义文件

     

       54
       54
       +
       - **模型生成**: 动态生成 Pydantic 模型类

     

       55
       55
       +
       - **引用解析**: 处理跨定义引用和联合类型

     

       56
       56
       +
       - **注册管理**: 模型注册表和缓存管理

     

       57
       57
       +
       - **兼容性验证**: 前向和后向兼容性检查

     

       58
       58
       +
       

     

       59
       59
       +
       ### 3. 核心功能特性

     

       60
       60
       +
       

     

       61
       61
       +
       #### 3.1 类型安全

     

       62
       62
       +
       - 基于 Pydantic 的强类型系统

     

       63
       63
       +
       - 运行时类型验证

     

       64
       64
       +
       - 自动类型转换和规范化

     

       65
       65
       +
       

     

       66
       66
       +
       #### 3.2 格式支持

     

       67
       67
       +
       - **JSON**: 符合 ATProto JSON 编码规范

     

       68
       68
       +
       - **DAG-CBOR**: 支持规范的 DAG-CBOR 编码

     

       69
       69
       +
       - **混合格式**: 支持两种格式间的转换

     

       70
       70
       +
       

     

       71
       71
       +
       #### 3.3 验证系统

     

       72
       72
       +
       - 语法验证 (基础数据类型)

     

       73
       73
       +
       - 语义验证 (业务规则和约束)

     

       74
       74
       +
       - 格式验证 (字符串格式如 datetime、uri、did 等)

     

       75
       75
       +
       - 引用验证 (CID、blob、跨定义引用)

     

       76
       76
       +
       

     

       77
       77
       +
       ### 4. 集成架构

     

       78
       78
       +
       

     

       79
       79
       +
       #### 4.1 与现有 URI 模块的集成

     

       80
       80
       +
       

     

       81
       81
       +
       ```python

     

       82
       82
       +
       # 示例：URI 与 Data 模块的集成

     

       83
       83
       +
       from atpasser.uri import URI, NSID

     

       84
       84
       +
       from atpasser.data import ATProtoSerializer

     

       85
       85
       +
       from atpasser.lexicon import LexiconRegistry

     

       86
       86
       +
       

     

       87
       87
       +
       # 解析 URI

     

       88
       88
       +
       uri = URI("at://example.com/com.example.blog.post/123")

     

       89
       89
       +
       

     

       90
       90
       +
       # 根据 NSID 获取对应的数据模型

     

       91
       91
       +
       model_class = LexiconRegistry.get_model(uri.collection.nsid)

     

       92
       92
       +
       

     

       93
       93
       +
       # 使用 Data 模块处理数据

     

       94
       94
       +
       serializer = ATProtoSerializer()

     

       95
       95
       +
       data = serializer.from_json(raw_data, model_class)

     

       96
       96
       +
       ```

     

       97
       97
       +
       

     

       98
       98
       +
       #### 4.2 数据流架构

     

       99
       99
       +
       

     

       100
       100
       +
       ```

     

       101
       101
       +
       原始数据 → Data 模块验证 → Lexicon 模型转换 → 序列化输出

     

       102
       102
       +
       Lexicon JSON → Lexicon 模块解析 → 生成 Pydantic 模型 → 注册到注册表

     

       103
       103
       +
       ```

     

       104
       104
       +
       

     

       105
       105
       +
       ### 5. 错误处理架构

     

       106
       106
       +
       

     

       107
       107
       +
       #### 5.1 统一的错误体系

     

       108
       108
       +
       

     

       109
       109
       +
       ```python

     

       110
       110
       +
       class ATProtoError(Exception):

     

       111
       111
       +
           """基础错误类"""

     

       112
       112
       +
           pass

     

       113
       113
       +
       

     

       114
       114
       +
       class DataError(ATProtoError):

     

       115
       115
       +
           """数据相关错误"""

     

       116
       116
       +
           pass

     

       117
       117
       +
       

     

       118
       118
       +
       class LexiconError(ATProtoError):

     

       119
       119
       +
           """Lexicon 相关错误"""

     

       120
       120
       +
           pass

     

       121
       121
       +
       

     

       122
       122
       +
       class URIError(ATProtoError):

     

       123
       123
       +
           """URI 相关错误"""

     

       124
       124
       +
           pass

     

       125
       125
       +
       ```

     

       126
       126
       +
       

     

       127
       127
       +
       #### 5.2 错误诊断

     

       128
       128
       +
       - **字段级错误定位**: 精确到具体字段的路径信息

     

       129
       129
       +
       - **上下文信息**: 包含验证时的输入数据和期望格式

     

       130
       130
       +
       - **建议修复**: 提供具体的修复建议

     

       131
       131
       +
       

     

       132
       132
       +
       ### 6. 性能优化策略

     

       133
       133
       +
       

     

       134
       134
       +
       #### 6.1 缓存机制

     

       135
       135
       +
       - **模型缓存**: 缓存已解析的 Lexicon 模型

     

       136
       136
       +
       - **序列化缓存**: 缓存序列化结果

     

       137
       137
       +
       - **引用解析缓存**: 缓存跨定义引用解析结果

     

       138
       138
       +
       

     

       139
       139
       +
       #### 6.2 懒加载

     

       140
       140
       +
       - 按需解析 Lexicon 定义

     

       141
       141
       +
       - 延迟模型生成直到实际使用

     

       142
       142
       +
       - 动态导入依赖模块

     

       143
       143
       +
       

     

       144
       144
       +
       ### 7. 扩展性设计

     

       145
       145
       +
       

     

       146
       146
       +
       #### 7.1 插件系统

     

       147
       147
       +
       - 支持自定义类型处理器

     

       148
       148
       +
       - 支持自定义验证规则

     

       149
       149
       +
       - 支持自定义序列化格式

     

       150
       150
       +
       

     

       151
       151
       +
       #### 7.2 中间件支持

     

       152
       152
       +
       - 预处理钩子 (数据清洗、转换)

     

       153
       153
       +
       - 后处理钩子 (日志记录、监控)

     

       154
       154
       +
       - 验证钩子 (自定义验证逻辑)

     

       155
       155
       +
       

     

       156
       156
       +
       ### 8. 实施路线图

     

       157
       157
       +
       

     

       158
       158
       +
       #### 阶段 1: 基础实现 (2-3 周)

     

       159
       159
       +
       - 实现 Data 模块基础类型和 JSON 序列化

     

       160
       160
       +
       - 实现 Lexicon 模块基础解析器

     

       161
       161
       +
       - 建立基本的错误处理系统

     

       162
       162
       +
       

     

       163
       163
       +
       #### 阶段 2: 完整功能 (3-4 周)

     

       164
       164
       +
       - 添加 CBOR 序列化支持

     

       165
       165
       +
       - 实现完整的验证系统

     

       166
       166
       +
       - 添加引用解析和联合类型支持

     

       167
       167
       +
       

     

       168
       168
       +
       #### 阶段 3: 优化增强 (2 周)

     

       169
       169
       +
       - 实现缓存和性能优化

     

       170
       170
       +
       - 添加高级格式验证

     

       171
       171
       +
       - 完善错误处理和诊断信息

     

       172
       172
       +
       

     

       173
       173
       +
       #### 阶段 4: 测试部署 (1-2 周)

     

       174
       174
       +
       - 编写完整的测试套件

     

       175
       175
       +
       - 性能测试和优化

     

       176
       176
       +
       - 文档编写和示例代码

     

       177
       177
       +
       

     

       178
       178
       +
       ### 9. 依赖管理

     

       179
       179
       +
       

     

       180
       180
       +
       #### 9.1 核心依赖

     

       181
       181
       +
       - `pydantic >=2.11.9`: 数据验证和模型定义

     

       182
       182
       +
       - `cbor2 >=5.7.0`: CBOR 序列化支持

     

       183
       183
       +
       - `py-cid >=0.3.0`: CID 处理支持

     

       184
       184
       +
       

     

       185
       185
       +
       #### 9.2 可选依赖

     

       186
       186
       +
       - `jsonpath-ng >=1.7.0`: JSONPath 支持

     

       187
       187
       +
       - `langcodes >=3.5.0`: 语言代码验证

     

       188
       188
       +
       

     

       189
       189
       +
       ### 10. 质量保证

     

       190
       190
       +
       

     

       191
       191
       +
       #### 10.1 测试策略

     

       192
       192
       +
       - **单元测试**: 覆盖所有核心功能

     

       193
       193
       +
       - **集成测试**: 测试模块间集成

     

       194
       194
       +
       - **兼容性测试**: 确保与规范兼容

     

       195
       195
       +
       - **性能测试**: 验证性能指标

     

       196
       196
       +
       

     

       197
       197
       +
       #### 10.2 代码质量

     

       198
       198
       +
       - 类型注解覆盖率达到 100%

     

       199
       199
       +
       - 测试覆盖率超过 90%

     

       200
       200
       +
       - 遵循 PEP 8 编码规范

     

       201
       201
       +
       - 详细的文档和示例

     

       202
       202
       +
       

     

       203
       203
       +
       ## 总结

     

       204
       204
       +
       

     

       205
       205
       +
       本架构设计提供了一个完整、可扩展的 ATProto 数据处理解决方案，充分利用了 Python 的类型系统和现有生态，同时保持了与 ATProto 规范的完全兼容性。模块化的设计使得各个组件可以独立开发和测试，同时也便于未来的扩展和维护。

+119

examples/basic_usage.py

···

       1
       1
       +
       """Basic usage examples for ATProto data and lexicon modules."""

     

       2
       2
       +
       

     

       3
       3
       +
       import json

     

       4
       4
       +
       from atpasser.data import serializer, CIDLink, DateTimeString

     

       5
       5
       +
       from atpasser.lexicon import parser, registry

     

       6
       6
       +
       

     

       7
       7
       +
       

     

       8
       8
       +
       def demonstrate_data_serialization():

     

       9
       9
       +
           """Demonstrate basic data serialization."""

     

       10
       10
       +
           print("=== Data Serialization Demo ===")

     

       11
       11
       +
       

     

       12
       12
       +
           # Create some sample data

     

       13
       13
       +
           sample_data = {

     

       14
       14
       +
               "title": "Hello ATProto",

     

       15
       15
       +
               "content": "This is a test post",

     

       16
       16
       +
               "createdAt": "2024-01-15T10:30:00.000Z",

     

       17
       17
       +
               "tags": ["atproto", "test", "demo"],

     

       18
       18
       +
               "cidLink": CIDLink(

     

       19
       19
       +
                   "bafyreidfayvfuwqa7qlnopdjiqrxzs6blmoeu4rujcjtnci5beludirz2a"

     

       20
       20
       +
               ),

     

       21
       21
       +
           }

     

       22
       22
       +
       

     

       23
       23
       +
           # Serialize to JSON

     

       24
       24
       +
           json_output = serializer.to_json(sample_data, indent=2)

     

       25
       25
       +
           print("JSON Output:")

     

       26
       26
       +
           print(json_output)

     

       27
       27
       +
       

     

       28
       28
       +
           # Deserialize back

     

       29
       29
       +
           deserialized = serializer.from_json(json_output)

     

       30
       30
       +
           print("\nDeserialized:")

     

       31
       31
       +
           print(deserialized)

     

       32
       32
       +
       

     

       33
       33
       +
           print()

     

       34
       34
       +
       

     

       35
       35
       +
       

     

       36
       36
       +
       def demonstrate_lexicon_parsing():

     

       37
       37
       +
           """Demonstrate Lexicon parsing."""

     

       38
       38
       +
           print("=== Lexicon Parsing Demo ===")

     

       39
       39
       +
       

     

       40
       40
       +
           # Sample Lexicon definition

     

       41
       41
       +
           sample_lexicon = {

     

       42
       42
       +
               "lexicon": 1,

     

       43
       43
       +
               "id": "com.example.blog.post",

     

       44
       44
       +
               "description": "A simple blog post record",

     

       45
       45
       +
               "defs": {

     

       46
       46
       +
                   "main": {

     

       47
       47
       +
                       "type": "record",

     

       48
       48
       +
                       "key": "literal:post",

     

       49
       49
       +
                       "record": {

     

       50
       50
       +
                           "type": "object",

     

       51
       51
       +
                           "properties": {

     

       52
       52
       +
                               "title": {"type": "string", "maxLength": 300},

     

       53
       53
       +
                               "content": {"type": "string"},

     

       54
       54
       +
                               "createdAt": {"type": "string", "format": "datetime"},

     

       55
       55
       +
                               "tags": {

     

       56
       56
       +
                                   "type": "array",

     

       57
       57
       +
                                   "items": {"type": "string"},

     

       58
       58
       +
                                   "maxLength": 10,

     

       59
       59
       +
                               },

     

       60
       60
       +
                           },

     

       61
       61
       +
                           "required": ["title", "content", "createdAt"],

     

       62
       62
       +
                       },

     

       63
       63
       +
                   }

     

       64
       64
       +
               },

     

       65
       65
       +
           }

     

       66
       66
       +
       

     

       67
       67
       +
           try:

     

       68
       68
       +
               # Parse and register the Lexicon

     

       69
       69
       +
               parser.parse_and_register(sample_lexicon)

     

       70
       70
       +
               print("Lexicon parsed and registered successfully!")

     

       71
       71
       +
       

     

       72
       72
       +
               # Get the generated model

     

       73
       73
       +
               model_class = registry.get_model("com.example.blog.post")

     

       74
       74
       +
               if model_class:

     

       75
       75
       +
                   print(f"Generated model: {model_class.__name__}")

     

       76
       76
       +
       

     

       77
       77
       +
                   # Create an instance using the model

     

       78
       78
       +
                   post_data = {

     

       79
       79
       +
                       "title": "Test Post",

     

       80
       80
       +
                       "content": "This is a test post content",

     

       81
       81
       +
                       "createdAt": "2024-01-15T10:30:00.000Z",

     

       82
       82
       +
                       "tags": ["test", "demo"],

     

       83
       83
       +
                   }

     

       84
       84
       +
       

     

       85
       85
       +
                   validated_post = model_class(**post_data)

     

       86
       86
       +
                   print(f"Validated post: {validated_post.model_dump()}")

     

       87
       87
       +
       

     

       88
       88
       +
           except Exception as e:

     

       89
       89
       +
               print(f"Error: {e}")

     

       90
       90
       +
       

     

       91
       91
       +
           print()

     

       92
       92
       +
       

     

       93
       93
       +
       

     

       94
       94
       +
       def demonstrate_custom_types():

     

       95
       95
       +
           """Demonstrate custom type validation."""

     

       96
       96
       +
           print("=== Custom Type Validation Demo ===")

     

       97
       97
       +
       

     

       98
       98
       +
           # DateTimeString validation

     

       99
       99
       +
           try:

     

       100
       100
       +
               valid_dt = DateTimeString("2024-01-15T10:30:00.000Z")

     

       101
       101
       +
               print(f"Valid datetime: {valid_dt}")

     

       102
       102
       +
           except Exception as e:

     

       103
       103
       +
               print(f"DateTime validation error: {e}")

     

       104
       104
       +
       

     

       105
       105
       +
           # Invalid datetime

     

       106
       106
       +
           try:

     

       107
       107
       +
               invalid_dt = DateTimeString("invalid-date")

     

       108
       108
       +
               print(f"Invalid datetime: {invalid_dt}")

     

       109
       109
       +
           except Exception as e:

     

       110
       110
       +
               print(f"DateTime validation caught: {e}")

     

       111
       111
       +
       

     

       112
       112
       +
           print()

     

       113
       113
       +
       

     

       114
       114
       +
       

     

       115
       115
       +
       if __name__ == "__main__":

     

       116
       116
       +
           demonstrate_data_serialization()

     

       117
       117
       +
           demonstrate_lexicon_parsing()

     

       118
       118
       +
           demonstrate_custom_types()

     

       119
       119
       +
           print("Demo completed!")

+11

src/atpasser/__init__.py

···

       1
       1
       +
       """ATProto Python implementation - Tools for Authenticated Transfer Protocol."""

     

       2
       2
       +
       

     

       3
       3
       +
       from . import uri

     

       4
       4
       +
       from . import data

     

       5
       5
       +
       from . import lexicon

     

       6
       6
       +
       

     

       7
       7
       +
       __all__ = ["uri", "data", "lexicon"]

     

       8
       8
       +
       

     

       9
       9
       +
       __version__ = "0.1.0"

     

       10
       10
       +
       __author__ = "diaowinner"

     

       11
       11
       +
       __email__ = "diaowinner@qq.com"

+215

src/atpasser/data/ARCHITECTURE.md

···

       1
       1
       +
       # ATProto 数据模型模块架构设计

     

       2
       2
       +
       

     

       3
       3
       +
       ## 概述

     

       4
       4
       +
       

     

       5
       5
       +
       本模块负责实现 ATProto 数据模型的序列化、反序列化和验证功能，支持 JSON 和 DAG-CBOR 两种格式的数据编码。

     

       6
       6
       +
       

     

       7
       7
       +
       ## 核心架构设计

     

       8
       8
       +
       

     

       9
       9
       +
       ### 1. 基础类型系统

     

       10
       10
       +
       

     

       11
       11
       +
       #### 1.1 基础类型映射

     

       12
       12
       +
       

     

       13
       13
       +
       ```python

     

       14
       14
       +
       # 基础类型映射

     

       15
       15
       +
       DATA_MODEL_TYPE_MAPPING = {

     

       16
       16
       +
           "null": NoneType,

     

       17
       17
       +
           "boolean": bool,

     

       18
       18
       +
           "integer": int,

     

       19
       19
       +
           "string": str,

     

       20
       20
       +
           "bytes": bytes,

     

       21
       21
       +
           "cid-link": CIDLink,

     

       22
       22
       +
           "blob": BlobRef,

     

       23
       23
       +
           "array": list,

     

       24
       24
       +
           "object": dict

     

       25
       25
       +
       }

     

       26
       26
       +
       ```

     

       27
       27
       +
       

     

       28
       28
       +
       #### 1.2 自定义字段类型

     

       29
       29
       +
       

     

       30
       30
       +
       - **CIDLink**: 处理 CID 链接，支持二进制和字符串表示

     

       31
       31
       +
       - **BlobRef**: 处理 blob 引用，支持新旧格式兼容

     

       32
       32
       +
       - **DateTimeString**: RFC 3339 日期时间格式验证

     

       33
       33
       +
       - **LanguageTag**: BCP 47 语言标签验证

     

       34
       34
       +
       

     

       35
       35
       +
       ### 2. 序列化器架构

     

       36
       36
       +
       

     

       37
       37
       +
       #### 2.1 序列化器层级结构

     

       38
       38
       +
       

     

       39
       39
       +
       ```

     

       40
       40
       +
       ATProtoSerializer

     

       41
       41
       +
       ├── JSONSerializer

     

       42
       42
       +
       │   ├── Normalizer

     

       43
       43
       +
       │   └── Denormalizer

     

       44
       44
       +
       └── CBORSerializer

     

       45
       45
       +
           ├── DAGCBOREncoder

     

       46
       46
       +
           └── DAGCBORDecoder

     

       47
       47
       +
       ```

     

       48
       48
       +
       

     

       49
       49
       +
       #### 2.2 序列化流程

     

       50
       50
       +
       

     

       51
       51
       +
       1. **数据验证**: 使用 Pydantic 模型验证数据

     

       52
       52
       +
       2. **格式转换**: 特殊类型转换（CID、bytes 等）

     

       53
       53
       +
       3. **编码**: 根据目标格式进行编码

     

       54
       54
       +
       4. **规范化**: 确保输出符合 ATProto 规范

     

       55
       55
       +
       

     

       56
       56
       +
       ### 3. 验证系统

     

       57
       57
       +
       

     

       58
       58
       +
       #### 3.1 验证层级

     

       59
       59
       +
       

     

       60
       60
       +
       1. **语法验证**: 基础数据类型验证

     

       61
       61
       +
       2. **格式验证**: 字符串格式验证（datetime、uri、did 等）

     

       62
       62
       +
       3. **约束验证**: 长度、范围、枚举等约束验证

     

       63
       63
       +
       4. **引用验证**: CID 和 blob 引用有效性验证

     

       64
       64
       +
       

     

       65
       65
       +
       #### 3.2 自定义验证器

     

       66
       66
       +
       

     

       67
       67
       +
       ```python

     

       68
       68
       +
       class DataModelValidator:

     

       69
       69
       +
           def validate_cid(self, value: str) -> bool:

     

       70
       70
       +
               """验证 CID 格式"""

     

       71
       71
       +
               pass

     

       72
       72
       +
           

     

       73
       73
       +
           def validate_datetime(self, value: str) -> bool:

     

       74
       74
       +
               """验证 RFC 3339 datetime 格式"""

     

       75
       75
       +
               pass

     

       76
       76
       +
           

     

       77
       77
       +
           def validate_did(self, value: str) -> bool:

     

       78
       78
       +
               """验证 DID 格式"""

     

       79
       79
       +
               pass

     

       80
       80
       +
           

     

       81
       81
       +
           def validate_handle(self, value: str) -> bool:

     

       82
       82
       +
               """验证 handle 格式"""

     

       83
       83
       +
               pass

     

       84
       84
       +
           

     

       85
       85
       +
           def validate_nsid(self, value: str) -> bool:

     

       86
       86
       +
               """验证 NSID 格式"""

     

       87
       87
       +
               pass

     

       88
       88
       +
       ```

     

       89
       89
       +
       

     

       90
       90
       +
       ### 4. 特殊类型处理

     

       91
       91
       +
       

     

       92
       92
       +
       #### 4.1 CID 链接处理

     

       93
       93
       +
       

     

       94
       94
       +
       ```python

     

       95
       95
       +
       class CIDLink:

     

       96
       96
       +
           """处理 CID 链接类型"""

     

       97
       97
       +
           

     

       98
       98
       +
           def __init__(self, cid: Union[str, bytes]):

     

       99
       99
       +
               self.cid = cid

     

       100
       100
       +
           

     

       101
       101
       +
           def to_json(self) -> dict:

     

       102
       102
       +
               """序列化为 JSON 格式: {"$link": "cid-string"}"""

     

       103
       103
       +
               return {"$link": str(self.cid)}

     

       104
       104
       +
           

     

       105
       105
       +
           def to_cbor(self) -> bytes:

     

       106
       106
       +
               """序列化为 DAG-CBOR 格式"""

     

       107
       107
       +
               pass

     

       108
       108
       +
       ```

     

       109
       109
       +
       

     

       110
       110
       +
       #### 4.2 Blob 引用处理

     

       111
       111
       +
       

     

       112
       112
       +
       ```python

     

       113
       113
       +
       class BlobRef:

     

       114
       114
       +
           """处理 blob 引用，支持新旧格式"""

     

       115
       115
       +
           

     

       116
       116
       +
           def __init__(self, ref: CIDLink, mime_type: str, size: int):

     

       117
       117
       +
               self.ref = ref

     

       118
       118
       +
               self.mime_type = mime_type

     

       119
       119
       +
               self.size = size

     

       120
       120
       +
           

     

       121
       121
       +
           def to_json(self) -> dict:

     

       122
       122
       +
               """序列化为 JSON 格式"""

     

       123
       123
       +
               return {

     

       124
       124
       +
                   "$type": "blob",

     

       125
       125
       +
                   "ref": self.ref.to_json(),

     

       126
       126
       +
                   "mimeType": self.mime_type,

     

       127
       127
       +
                   "size": self.size

     

       128
       128
       +
               }

     

       129
       129
       +
           

     

       130
       130
       +
           @classmethod

     

       131
       131
       +
           def from_legacy(cls, data: dict):

     

       132
       132
       +
               """从旧格式解析"""

     

       133
       133
       +
               pass

     

       134
       134
       +
       ```

     

       135
       135
       +
       

     

       136
       136
       +
       ### 5. 错误处理系统

     

       137
       137
       +
       

     

       138
       138
       +
       #### 5.1 错误类型体系

     

       139
       139
       +
       

     

       140
       140
       +
       ```python

     

       141
       141
       +
       class DataModelError(Exception):

     

       142
       142
       +
           """基础数据模型错误"""

     

       143
       143
       +
           pass

     

       144
       144
       +
       

     

       145
       145
       +
       class SerializationError(DataModelError):

     

       146
       146
       +
           """序列化错误"""

     

       147
       147
       +
           pass

     

       148
       148
       +
       

     

       149
       149
       +
       class ValidationError(DataModelError):

     

       150
       150
       +
           """验证错误"""

     

       151
       151
       +
           pass

     

       152
       152
       +
       

     

       153
       153
       +
       class FormatError(DataModelError):

     

       154
       154
       +
           """格式错误"""

     

       155
       155
       +
           pass

     

       156
       156
       +
       ```

     

       157
       157
       +
       

     

       158
       158
       +
       #### 5.2 错误消息格式

     

       159
       159
       +
       

     

       160
       160
       +
       - **详细路径信息**: 包含字段路径

     

       161
       161
       +
       - **期望值描述**: 明确的期望格式说明

     

       162
       162
       +
       - **上下文信息**: 验证时的上下文数据

     

       163
       163
       +
       

     

       164
       164
       +
       ### 6. 模块文件结构

     

       165
       165
       +
       

     

       166
       166
       +
       ```

     

       167
       167
       +
       src/atpasser/data/

     

       168
       168
       +
       ├── __init__.py              # 模块导出

     

       169
       169
       +
       ├── ARCHITECTURE.md          # 架构文档

     

       170
       170
       +
       ├── types.py                 # 基础类型定义

     

       171
       171
       +
       ├── serializer.py            # 序列化器实现

     

       172
       172
       +
       ├── validator.py             # 验证器实现

     

       173
       173
       +
       ├── exceptions.py            # 异常定义

     

       174
       174
       +
       ├── cid.py                   # CID 链接处理

     

       175
       175
       +
       ├── blob.py                  # Blob 引用处理

     

       176
       176
       +
       └── formats.py               # 格式验证器

     

       177
       177
       +
       ```

     

       178
       178
       +
       

     

       179
       179
       +
       ### 7. 依赖关系

     

       180
       180
       +
       

     

       181
       181
       +
       - **内部依赖**: `src/atpasser/uri` (NSID、DID、Handle 验证)

     

       182
       182
       +
       - **外部依赖**: 

     

       183
       183
       +
         - `pydantic`: 数据验证

     

       184
       184
       +
         - `cbor2`: CBOR 序列化

     

       185
       185
       +
         - `py-cid`: CID 处理

     

       186
       186
       +
       

     

       187
       187
       +
       ## 实现策略

     

       188
       188
       +
       

     

       189
       189
       +
       ### 1. 渐进式实现

     

       190
       190
       +
       

     

       191
       191
       +
       1. **阶段一**: 实现基础类型和 JSON 序列化

     

       192
       192
       +
       2. **阶段二**: 添加 CBOR 序列化和验证器

     

       193
       193
       +
       3. **阶段三**: 实现高级格式验证

     

       194
       194
       +
       4. **阶段四**: 性能优化和内存管理

     

       195
       195
       +
       

     

       196
       196
       +
       ### 2. 测试策略

     

       197
       197
       +
       

     

       198
       198
       +
       - **单元测试**: 测试各个组件功能

     

       199
       199
       +
       - **集成测试**: 测试端到端数据流

     

       200
       200
       +
       - **兼容性测试**: 确保与现有实现兼容

     

       201
       201
       +
       - **性能测试**: 验证序列化性能

     

       202
       202
       +
       

     

       203
       203
       +
       ### 3. 扩展性考虑

     

       204
       204
       +
       

     

       205
       205
       +
       - **插件系统**: 支持自定义格式验证

     

       206
       206
       +
       - **中间件**: 支持预处理和后处理钩子

     

       207
       207
       +
       - **缓存**: 序列化结果缓存优化

     

       208
       208
       +
       

     

       209
       209
       +
       ## 优势

     

       210
       210
       +
       

     

       211
       211
       +
       1. **类型安全**: 基于 Pydantic 的强类型系统

     

       212
       212
       +
       2. **性能**: 优化的序列化实现

     

       213
       213
       +
       3. **兼容性**: 支持新旧格式兼容

     

       214
       214
       +
       4. **可扩展**: 模块化设计支持未来扩展

     

       215
       215
       +
       5. **错误友好**: 详细的错误消息和诊断信息

+47

src/atpasser/data/__init__.py

···

       1
       1
       +
       """ATProto data model module for serialization and validation."""

     

       2
       2
       +
       

     

       3
       3
       +
       from .exceptions import (

     

       4
       4
       +
           DataModelError,

     

       5
       5
       +
           SerializationError,

     

       6
       6
       +
           ValidationError,

     

       7
       7
       +
           FormatError,

     

       8
       8
       +
           CIDError,

     

       9
       9
       +
           BlobError,

     

       10
       10
       +
       )

     

       11
       11
       +
       

     

       12
       12
       +
       from .types import (

     

       13
       13
       +
           CIDLink,

     

       14
       14
       +
           DateTimeString,

     

       15
       15
       +
           LanguageTag,

     

       16
       16
       +
           ATUri,

     

       17
       17
       +
           DIDString,

     

       18
       18
       +
           HandleString,

     

       19
       19
       +
           NSIDString,

     

       20
       20
       +
       )

     

       21
       21
       +
       

     

       22
       22
       +
       from .formats import format_validator, FormatValidator

     

       23
       23
       +
       from .serializer import ATProtoSerializer, serializer

     

       24
       24
       +
       

     

       25
       25
       +
       __all__ = [

     

       26
       26
       +
           # Exceptions

     

       27
       27
       +
           "DataModelError",

     

       28
       28
       +
           "SerializationError",

     

       29
       29
       +
           "ValidationError",

     

       30
       30
       +
           "FormatError",

     

       31
       31
       +
           "CIDError",

     

       32
       32
       +
           "BlobError",

     

       33
       33
       +
           # Types

     

       34
       34
       +
           "CIDLink",

     

       35
       35
       +
           "DateTimeString",

     

       36
       36
       +
           "LanguageTag",

     

       37
       37
       +
           "ATUri",

     

       38
       38
       +
           "DIDString",

     

       39
       39
       +
           "HandleString",

     

       40
       40
       +
           "NSIDString",

     

       41
       41
       +
           # Validators

     

       42
       42
       +
           "format_validator",

     

       43
       43
       +
           "FormatValidator",

     

       44
       44
       +
           # Serializers

     

       45
       45
       +
           "ATProtoSerializer",

     

       46
       46
       +
           "serializer",

     

       47
       47
       +
       ]

+87

src/atpasser/data/exceptions.py

···

       1
       1
       +
       """Exceptions for ATProto data model module."""

     

       2
       2
       +
       

     

       3
       3
       +
       from typing import Optional

     

       4
       4
       +
       

     

       5
       5
       +
       

     

       6
       6
       +
       class DataModelError(Exception):

     

       7
       7
       +
           """Base exception for data model errors."""

     

       8
       8
       +
       

     

       9
       9
       +
           def __init__(self, message: str, details: Optional[str] = None):

     

       10
       10
       +
               self.message = message

     

       11
       11
       +
               self.details = details

     

       12
       12
       +
               super().__init__(message)

     

       13
       13
       +
       

     

       14
       14
       +
       

     

       15
       15
       +
       class SerializationError(DataModelError):

     

       16
       16
       +
           """Raised when serialization fails."""

     

       17
       17
       +
       

     

       18
       18
       +
           def __init__(self, message: str, details: Optional[str] = None):

     

       19
       19
       +
               super().__init__(f"Serialization error: {message}", details)

     

       20
       20
       +
       

     

       21
       21
       +
       

     

       22
       22
       +
       class ValidationError(DataModelError):

     

       23
       23
       +
           """Raised when data validation fails."""

     

       24
       24
       +
       

     

       25
       25
       +
           def __init__(

     

       26
       26
       +
               self,

     

       27
       27
       +
               message: str,

     

       28
       28
       +
               field_path: Optional[str] = None,

     

       29
       29
       +
               expected: Optional[str] = None,

     

       30
       30
       +
               actual: Optional[str] = None,

     

       31
       31
       +
           ):

     

       32
       32
       +
               self.fieldPath = field_path

     

       33
       33
       +
               self.expected = expected

     

       34
       34
       +
               self.actual = actual

     

       35
       35
       +
       

     

       36
       36
       +
               details = []

     

       37
       37
       +
               if field_path:

     

       38
       38
       +
                   details.append(f"Field: {field_path}")

     

       39
       39
       +
               if expected:

     

       40
       40
       +
                   details.append(f"Expected: {expected}")

     

       41
       41
       +
               if actual:

     

       42
       42
       +
                   details.append(f"Actual: {actual}")

     

       43
       43
       +
       

     

       44
       44
       +
               super().__init__(

     

       45
       45
       +
                   f"Validation error: {message}", "; ".join(details) if details else None

     

       46
       46
       +
               )

     

       47
       47
       +
       

     

       48
       48
       +
       

     

       49
       49
       +
       class FormatError(DataModelError):

     

       50
       50
       +
           """Raised when format validation fails."""

     

       51
       51
       +
       

     

       52
       52
       +
           def __init__(

     

       53
       53
       +
               self,

     

       54
       54
       +
               message: str,

     

       55
       55
       +
               format_type: Optional[str] = None,

     

       56
       56
       +
               value: Optional[str] = None,

     

       57
       57
       +
           ):

     

       58
       58
       +
               self.formatType = format_type

     

       59
       59
       +
               self.value = value

     

       60
       60
       +
       

     

       61
       61
       +
               details = []

     

       62
       62
       +
               if format_type:

     

       63
       63
       +
                   details.append(f"Format: {format_type}")

     

       64
       64
       +
               if value:

     

       65
       65
       +
                   details.append(f"Value: {value}")

     

       66
       66
       +
       

     

       67
       67
       +
               super().__init__(

     

       68
       68
       +
                   f"Format error: {message}", "; ".join(details) if details else None

     

       69
       69
       +
               )

     

       70
       70
       +
       

     

       71
       71
       +
       

     

       72
       72
       +
       class CIDError(DataModelError):

     

       73
       73
       +
           """Raised when CID processing fails."""

     

       74
       74
       +
       

     

       75
       75
       +
           def __init__(self, message: str, cid: Optional[str] = None):

     

       76
       76
       +
               self.cid = cid

     

       77
       77
       +
               super().__init__(f"CID error: {message}", f"CID: {cid}" if cid else None)

     

       78
       78
       +
       

     

       79
       79
       +
       

     

       80
       80
       +
       class BlobError(DataModelError):

     

       81
       81
       +
           """Raised when blob processing fails."""

     

       82
       82
       +
       

     

       83
       83
       +
           def __init__(self, message: str, blob_ref: Optional[str] = None):

     

       84
       84
       +
               self.blobRef = blob_ref

     

       85
       85
       +
               super().__init__(

     

       86
       86
       +
                   f"Blob error: {message}", f"Blob ref: {blob_ref}" if blob_ref else None

     

       87
       87
       +
               )

+190

src/atpasser/data/formats.py

···

       1
       1
       +
       """Format validators for ATProto data model."""

     

       2
       2
       +
       

     

       3
       3
       +
       import re

     

       4
       4
       +
       from typing import Any, Optional

     

       5
       5
       +
       from .exceptions import FormatError

     

       6
       6
       +
       

     

       7
       7
       +
       

     

       8
       8
       +
       class FormatValidator:

     

       9
       9
       +
           """Validates string formats according to ATProto specifications."""

     

       10
       10
       +
       

     

       11
       11
       +
           @staticmethod

     

       12
       12
       +
           def validate_datetime(value: str) -> str:

     

       13
       13
       +
               """Validate RFC 3339 datetime format."""

     

       14
       14
       +
               # RFC 3339 pattern with strict validation

     

       15
       15
       +
               pattern = (

     

       16
       16
       +
                   r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$"

     

       17
       17
       +
               )

     

       18
       18
       +
               if not re.match(pattern, value):

     

       19
       19
       +
                   raise FormatError("Invalid RFC 3339 datetime format", "datetime", value)

     

       20
       20
       +
       

     

       21
       21
       +
               # Additional semantic validation

     

       22
       22
       +
               try:

     

       23
       23
       +
                   # Extract date parts for validation

     

       24
       24
       +
                   date_part, time_part = value.split("T", 1)

     

       25
       25
       +
                   year, month, day = map(int, date_part.split("-"))

     

       26
       26
       +
       

     

       27
       27
       +
                   # Basic date validation

     

       28
       28
       +
                   if not (1 <= month <= 12):

     

       29
       29
       +
                       raise FormatError("Month must be between 01 and 12", "datetime", value)

     

       30
       30
       +
                   if not (1 <= day <= 31):

     

       31
       31
       +
                       raise FormatError("Day must be between 01 and 31", "datetime", value)

     

       32
       32
       +
                   if year < 0:

     

       33
       33
       +
                       raise FormatError("Year must be positive", "datetime", value)

     

       34
       34
       +
       

     

       35
       35
       +
               except ValueError:

     

       36
       36
       +
                   raise FormatError("Invalid datetime structure", "datetime", value)

     

       37
       37
       +
       

     

       38
       38
       +
               return value

     

       39
       39
       +
       

     

       40
       40
       +
           @staticmethod

     

       41
       41
       +
           def validate_did(value: str) -> str:

     

       42
       42
       +
               """Validate DID format."""

     

       43
       43
       +
               pattern = r"^did:[a-z]+:[a-zA-Z0-9._:%-]*[a-zA-Z0-9._-]$"

     

       44
       44
       +
               if not re.match(pattern, value):

     

       45
       45
       +
                   raise FormatError("Invalid DID format", "did", value)

     

       46
       46
       +
       

     

       47
       47
       +
               if len(value) > 2048:

     

       48
       48
       +
                   raise FormatError("DID too long", "did", value)

     

       49
       49
       +
       

     

       50
       50
       +
               return value

     

       51
       51
       +
       

     

       52
       52
       +
           @staticmethod

     

       53
       53
       +
           def validate_handle(value: str) -> str:

     

       54
       54
       +
               """Validate handle format."""

     

       55
       55
       +
               if len(value) > 253:

     

       56
       56
       +
                   raise FormatError("Handle too long", "handle", value)

     

       57
       57
       +
       

     

       58
       58
       +
               labels = value.lower().split(".")

     

       59
       59
       +
               if len(labels) < 2:

     

       60
       60
       +
                   raise FormatError("Handle must contain at least one dot", "handle", value)

     

       61
       61
       +
       

     

       62
       62
       +
               for i, label in enumerate(labels):

     

       63
       63
       +
                   if not (1 <= len(label) <= 63):

     

       64
       64
       +
                       raise FormatError(

     

       65
       65
       +
                           f"Label {i+1} length must be 1-63 characters", "handle", value

     

       66
       66
       +
                       )

     

       67
       67
       +
       

     

       68
       68
       +
                   if not re.match(r"^[a-z0-9-]+$", label):

     

       69
       69
       +
                       raise FormatError(

     

       70
       70
       +
                           f"Label {i+1} contains invalid characters", "handle", value

     

       71
       71
       +
                       )

     

       72
       72
       +
       

     

       73
       73
       +
                   if label.startswith("-") or label.endswith("-"):

     

       74
       74
       +
                       raise FormatError(

     

       75
       75
       +
                           f"Label {i+1} cannot start or end with hyphen", "handle", value

     

       76
       76
       +
                       )

     

       77
       77
       +
       

     

       78
       78
       +
               if labels[-1][0].isdigit():

     

       79
       79
       +
                   raise FormatError("TLD cannot start with digit", "handle", value)

     

       80
       80
       +
       

     

       81
       81
       +
               return value

     

       82
       82
       +
       

     

       83
       83
       +
           @staticmethod

     

       84
       84
       +
           def validate_nsid(value: str) -> str:

     

       85
       85
       +
               """Validate NSID format."""

     

       86
       86
       +
               if len(value) > 317:

     

       87
       87
       +
                   raise FormatError("NSID too long", "nsid", value)

     

       88
       88
       +
       

     

       89
       89
       +
               if not all(ord(c) < 128 for c in value):

     

       90
       90
       +
                   raise FormatError("NSID must contain only ASCII characters", "nsid", value)

     

       91
       91
       +
       

     

       92
       92
       +
               if value.startswith(".") or value.endswith("."):

     

       93
       93
       +
                   raise FormatError("NSID cannot start or end with dot", "nsid", value)

     

       94
       94
       +
       

     

       95
       95
       +
               segments = value.split(".")

     

       96
       96
       +
               if len(segments) < 3:

     

       97
       97
       +
                   raise FormatError("NSID must have at least 3 segments", "nsid", value)

     

       98
       98
       +
       

     

       99
       99
       +
               # Validate domain authority segments

     

       100
       100
       +
               for i, segment in enumerate(segments[:-1]):

     

       101
       101
       +
                   if not (1 <= len(segment) <= 63):

     

       102
       102
       +
                       raise FormatError(

     

       103
       103
       +
                           f"Domain segment {i+1} length must be 1-63", "nsid", value

     

       104
       104
       +
                       )

     

       105
       105
       +
       

     

       106
       106
       +
                   if not re.match(r"^[a-z0-9-]+$", segment):

     

       107
       107
       +
                       raise FormatError(

     

       108
       108
       +
                           f"Domain segment {i+1} contains invalid chars", "nsid", value

     

       109
       109
       +
                       )

     

       110
       110
       +
       

     

       111
       111
       +
                   if segment.startswith("-") or segment.endswith("-"):

     

       112
       112
       +
                       raise FormatError(

     

       113
       113
       +
                           f"Domain segment {i+1} cannot start/end with hyphen", "nsid", value

     

       114
       114
       +
                       )

     

       115
       115
       +
       

     

       116
       116
       +
               # Validate name segment

     

       117
       117
       +
               name = segments[-1]

     

       118
       118
       +
               if not (1 <= len(name) <= 63):

     

       119
       119
       +
                   raise FormatError("Name segment length must be 1-63", "nsid", value)

     

       120
       120
       +
       

     

       121
       121
       +
               if not re.match(r"^[a-zA-Z0-9]+$", name):

     

       122
       122
       +
                   raise FormatError("Name segment contains invalid characters", "nsid", value)

     

       123
       123
       +
       

     

       124
       124
       +
               if name[0].isdigit():

     

       125
       125
       +
                   raise FormatError("Name segment cannot start with digit", "nsid", value)

     

       126
       126
       +
       

     

       127
       127
       +
               return value

     

       128
       128
       +
       

     

       129
       129
       +
           @staticmethod

     

       130
       130
       +
           def validate_uri(value: str) -> str:

     

       131
       131
       +
               """Validate URI format."""

     

       132
       132
       +
               if len(value) > 8192:  # 8 KB limit

     

       133
       133
       +
                   raise FormatError("URI too long", "uri", value)

     

       134
       134
       +
       

     

       135
       135
       +
               # Basic URI pattern validation

     

       136
       136
       +
               uri_pattern = r"^[a-zA-Z][a-zA-Z0-9+.-]*:.*$"

     

       137
       137
       +
               if not re.match(uri_pattern, value):

     

       138
       138
       +
                   raise FormatError("Invalid URI format", "uri", value)

     

       139
       139
       +
       

     

       140
       140
       +
               return value

     

       141
       141
       +
       

     

       142
       142
       +
           @staticmethod

     

       143
       143
       +
           def validate_cid(value: str) -> str:

     

       144
       144
       +
               """Validate CID format."""

     

       145
       145
       +
               # Basic CID pattern validation (simplified)

     

       146
       146
       +
               cid_pattern = r"^[a-zA-Z0-9]+$"

     

       147
       147
       +
               if not re.match(cid_pattern, value):

     

       148
       148
       +
                   raise FormatError("Invalid CID format", "cid", value)

     

       149
       149
       +
       

     

       150
       150
       +
               return value

     

       151
       151
       +
       

     

       152
       152
       +
           @staticmethod

     

       153
       153
       +
           def validate_at_identifier(value: str) -> str:

     

       154
       154
       +
               """Validate at-identifier format (DID or handle)."""

     

       155
       155
       +
               try:

     

       156
       156
       +
                   # Try DID first

     

       157
       157
       +
                   return FormatValidator.validate_did(value)

     

       158
       158
       +
               except FormatError:

     

       159
       159
       +
                   try:

     

       160
       160
       +
                       # Fall back to handle

     

       161
       161
       +
                       return FormatValidator.validate_handle(value)

     

       162
       162
       +
                   except FormatError:

     

       163
       163
       +
                       raise FormatError(

     

       164
       164
       +
                           "Invalid at-identifier (not a DID or handle)",

     

       165
       165
       +
                           "at-identifier",

     

       166
       166
       +
                           value,

     

       167
       167
       +
                       )

     

       168
       168
       +
       

     

       169
       169
       +
           @staticmethod

     

       170
       170
       +
           def validate_at_uri(value: str) -> str:

     

       171
       171
       +
               """Validate at-uri format."""

     

       172
       172
       +
               if not value.startswith("at://"):

     

       173
       173
       +
                   raise FormatError("AT URI must start with 'at://'", "at-uri", value)

     

       174
       174
       +
       

     

       175
       175
       +
               # Additional validation can be added here

     

       176
       176
       +
               return value

     

       177
       177
       +
       

     

       178
       178
       +
           @staticmethod

     

       179
       179
       +
           def validate_language(value: str) -> str:

     

       180
       180
       +
               """Validate language tag format."""

     

       181
       181
       +
               # BCP 47 pattern validation

     

       182
       182
       +
               pattern = r"^[a-zA-Z]{1,8}(?:-[a-zA-Z0-9]{1,8})*$"

     

       183
       183
       +
               if not re.match(pattern, value):

     

       184
       184
       +
                   raise FormatError("Invalid language tag format", "language", value)

     

       185
       185
       +
       

     

       186
       186
       +
               return value

     

       187
       187
       +
       

     

       188
       188
       +
       

     

       189
       189
       +
       # Global validator instance

     

       190
       190
       +
       format_validator = FormatValidator()

+125

src/atpasser/data/serializer.py

···

       1
       1
       +
       """Serializer for ATProto data model formats."""

     

       2
       2
       +
       

     

       3
       3
       +
       import json

     

       4
       4
       +
       import base64

     

       5
       5
       +
       from typing import Any, Dict, Type, Union, Optional

     

       6
       6
       +
       from pydantic import BaseModel

     

       7
       7
       +
       from .exceptions import SerializationError, ValidationError

     

       8
       8
       +
       from .types import CIDLink

     

       9
       9
       +
       

     

       10
       10
       +
       

     

       11
       11
       +
       class ATProtoSerializer:

     

       12
       12
       +
           """Serializer for ATProto JSON and CBOR formats."""

     

       13
       13
       +
       

     

       14
       14
       +
           def __init__(self):

     

       15
       15
       +
               self.json_encoder = JSONEncoder()

     

       16
       16
       +
               self.json_decoder = JSONDecoder()

     

       17
       17
       +
       

     

       18
       18
       +
           def to_json(self, obj: Any, indent: Optional[int] = None) -> str:

     

       19
       19
       +
               """Serialize object to ATProto JSON format."""

     

       20
       20
       +
               try:

     

       21
       21
       +
                   if isinstance(obj, BaseModel):

     

       22
       22
       +
                       obj = obj.model_dump(mode="json")

     

       23
       23
       +
       

     

       24
       24
       +
                   serialized = self.json_encoder.encode(obj)

     

       25
       25
       +
                   return json.dumps(serialized, indent=indent, ensure_ascii=False)

     

       26
       26
       +
               except Exception as e:

     

       27
       27
       +
                   raise SerializationError(f"JSON serialization failed: {str(e)}")

     

       28
       28
       +
       

     

       29
       29
       +
           def from_json(

     

       30
       30
       +
               self, data: Union[str, bytes, dict], model: Optional[Type[BaseModel]] = None

     

       31
       31
       +
           ) -> Any:

     

       32
       32
       +
               """Deserialize from ATProto JSON format."""

     

       33
       33
       +
               try:

     

       34
       34
       +
                   if isinstance(data, (str, bytes)):

     

       35
       35
       +
                       data = json.loads(data)

     

       36
       36
       +
       

     

       37
       37
       +
                   decoded = self.json_decoder.decode(data)

     

       38
       38
       +
       

     

       39
       39
       +
                   if model and issubclass(model, BaseModel):

     

       40
       40
       +
                       return model.model_validate(decoded)

     

       41
       41
       +
                   return decoded

     

       42
       42
       +
               except Exception as e:

     

       43
       43
       +
                   raise SerializationError(f"JSON deserialization failed: {str(e)}")

     

       44
       44
       +
       

     

       45
       45
       +
           def to_cbor(self, obj: Any) -> bytes:

     

       46
       46
       +
               """Serialize object to DAG-CBOR format."""

     

       47
       47
       +
               try:

     

       48
       48
       +
                   # This is a placeholder - actual CBOR implementation would go here

     

       49
       49
       +
                   # For now, we'll convert to JSON and then encode as bytes

     

       50
       50
       +
                   json_str = self.to_json(obj)

     

       51
       51
       +
                   return json_str.encode("utf-8")

     

       52
       52
       +
               except Exception as e:

     

       53
       53
       +
                   raise SerializationError(f"CBOR serialization failed: {str(e)}")

     

       54
       54
       +
       

     

       55
       55
       +
           def from_cbor(self, data: bytes, model: Optional[Type[BaseModel]] = None) -> Any:

     

       56
       56
       +
               """Deserialize from DAG-CBOR format."""

     

       57
       57
       +
               try:

     

       58
       58
       +
                   # This is a placeholder - actual CBOR implementation would go here

     

       59
       59
       +
                   # For now, we'll decode from bytes and then parse JSON

     

       60
       60
       +
                   json_str = data.decode("utf-8")

     

       61
       61
       +
                   return self.from_json(json_str, model)

     

       62
       62
       +
               except Exception as e:

     

       63
       63
       +
                   raise SerializationError(f"CBOR deserialization failed: {str(e)}")

     

       64
       64
       +
       

     

       65
       65
       +
       

     

       66
       66
       +
       class JSONEncoder:

     

       67
       67
       +
           """Encodes Python objects to ATProto JSON format."""

     

       68
       68
       +
       

     

       69
       69
       +
           def encode(self, obj: Any) -> Any:

     

       70
       70
       +
               """Recursively encode object to ATProto JSON format."""

     

       71
       71
       +
               if isinstance(obj, dict):

     

       72
       72
       +
                   return {k: self.encode(v) for k, v in obj.items()}

     

       73
       73
       +
               elif isinstance(obj, list):

     

       74
       74
       +
                   return [self.encode(item) for item in obj]

     

       75
       75
       +
               elif isinstance(obj, CIDLink):

     

       76
       76
       +
                   return obj.to_json()

     

       77
       77
       +
               elif isinstance(obj, bytes):

     

       78
       78
       +
                   return self._encode_bytes(obj)

     

       79
       79
       +
               else:

     

       80
       80
       +
                   return obj

     

       81
       81
       +
       

     

       82
       82
       +
           def _encode_bytes(self, data: bytes) -> Dict[str, str]:

     

       83
       83
       +
               """Encode bytes to ATProto bytes format."""

     

       84
       84
       +
               return {"$bytes": base64.b64encode(data).decode("ascii")}

     

       85
       85
       +
       

     

       86
       86
       +
       

     

       87
       87
       +
       class JSONDecoder:

     

       88
       88
       +
           """Decodes ATProto JSON format to Python objects."""

     

       89
       89
       +
       

     

       90
       90
       +
           def decode(self, obj: Any) -> Any:

     

       91
       91
       +
               """Recursively decode ATProto JSON format to Python objects."""

     

       92
       92
       +
               if isinstance(obj, dict):

     

       93
       93
       +
                   return self._decode_object(obj)

     

       94
       94
       +
               elif isinstance(obj, list):

     

       95
       95
       +
                   return [self.decode(item) for item in obj]

     

       96
       96
       +
               else:

     

       97
       97
       +
                   return obj

     

       98
       98
       +
       

     

       99
       99
       +
           def _decode_object(self, obj: Dict[str, Any]) -> Any:

     

       100
       100
       +
               """Decode a JSON object, handling special ATProto formats."""

     

       101
       101
       +
               if len(obj) == 1:

     

       102
       102
       +
                   key = next(iter(obj.keys()))

     

       103
       103
       +
                   value = obj[key]

     

       104
       104
       +
       

     

       105
       105
       +
                   if key == "$link" and isinstance(value, str):

     

       106
       106
       +
                       return CIDLink(value)

     

       107
       107
       +
                   elif key == "$bytes" and isinstance(value, str):

     

       108
       108
       +
                       return self._decode_bytes(value)

     

       109
       109
       +
                   elif key == "$type" and value == "blob":

     

       110
       110
       +
                       # This would be handled by a blob-specific decoder

     

       111
       111
       +
                       return obj

     

       112
       112
       +
       

     

       113
       113
       +
               # Regular object - decode recursively

     

       114
       114
       +
               return {k: self.decode(v) for k, v in obj.items()}

     

       115
       115
       +
       

     

       116
       116
       +
           def _decode_bytes(self, value: str) -> bytes:

     

       117
       117
       +
               """Decode ATProto bytes format."""

     

       118
       118
       +
               try:

     

       119
       119
       +
                   return base64.b64decode(value)

     

       120
       120
       +
               except Exception as e:

     

       121
       121
       +
                   raise SerializationError(f"Invalid base64 encoding: {str(e)}")

     

       122
       122
       +
       

     

       123
       123
       +
       

     

       124
       124
       +
       # Global serializer instance

     

       125
       125
       +
       serializer = ATProtoSerializer()

+263

src/atpasser/lexicon/ARCHITECTURE.md

···

       1
       1
       +
       # ATProto Lexicon 模块架构设计

     

       2
       2
       +
       

     

       3
       3
       +
       ## 概述

     

       4
       4
       +
       

     

       5
       5
       +
       本模块负责解析、验证和管理 ATProto Lexicon 定义文件，将 JSON Schema 转换为可执行的 Pydantic 模型，并提供类型安全的接口。

     

       6
       6
       +
       

     

       7
       7
       +
       ## 核心架构设计

     

       8
       8
       +
       

     

       9
       9
       +
       ### 1. Lexicon 解析系统

     

       10
       10
       +
       

     

       11
       11
       +
       #### 1.1 解析器层级结构

     

       12
       12
       +
       

     

       13
       13
       +
       ```

     

       14
       14
       +
       LexiconParser

     

       15
       15
       +
       ├── DefinitionParser

     

       16
       16
       +
       │   ├── PrimaryDefinitionParser

     

       17
       17
       +
       │   │   ├── RecordParser

     

       18
       18
       +
       │   │   ├── QueryParser

     

       19
       19
       +
       │   │   ├── ProcedureParser

     

       20
       20
       +
       │   │   └── SubscriptionParser

     

       21
       21
       +
       │   └── FieldDefinitionParser

     

       22
       22
       +
       │       ├── SimpleTypeParser

     

       23
       23
       +
       │       ├── CompoundTypeParser

     

       24
       24
       +
       │       └── MetaTypeParser

     

       25
       25
       +
       └── Validator

     

       26
       26
       +
           ├── SchemaValidator

     

       27
       27
       +
           └── CrossReferenceValidator

     

       28
       28
       +
       ```

     

       29
       29
       +
       

     

       30
       30
       +
       #### 1.2 解析流程

     

       31
       31
       +
       

     

       32
       32
       +
       1. **加载 Lexicon JSON**: 读取并验证 Lexicon 文件结构

     

       33
       33
       +
       2. **解析定义**: 根据类型分发到相应的解析器

     

       34
       34
       +
       3. **构建模型**: 生成对应的 Pydantic 模型类

     

       35
       35
       +
       4. **验证引用**: 检查跨定义引用的有效性

     

       36
       36
       +
       5. **注册模型**: 将模型注册到全局注册表

     

       37
       37
       +
       

     

       38
       38
       +
       ### 2. 类型映射系统

     

       39
       39
       +
       

     

       40
       40
       +
       #### 2.1 Lexicon 类型到 Python 类型映射

     

       41
       41
       +
       

     

       42
       42
       +
       ```python

     

       43
       43
       +
       LEXICON_TYPE_MAPPING = {

     

       44
       44
       +
           "null": None,

     

       45
       45
       +
           "boolean": bool,

     

       46
       46
       +
           "integer": int,

     

       47
       47
       +
           "string": str,

     

       48
       48
       +
           "bytes": bytes,

     

       49
       49
       +
           "cid-link": "CIDLink",

     

       50
       50
       +
           "blob": "BlobRef",

     

       51
       51
       +
           "array": list,

     

       52
       52
       +
           "object": dict,

     

       53
       53
       +
           "params": dict,

     

       54
       54
       +
           "token": "LexiconToken",

     

       55
       55
       +
           "ref": "LexiconRef",

     

       56
       56
       +
           "union": "LexiconUnion",

     

       57
       57
       +
           "unknown": Any,

     

       58
       58
       +
           "record": "RecordModel",

     

       59
       59
       +
           "query": "QueryModel",

     

       60
       60
       +
           "procedure": "ProcedureModel",

     

       61
       61
       +
           "subscription": "SubscriptionModel"

     

       62
       62
       +
       }

     

       63
       63
       +
       ```

     

       64
       64
       +
       

     

       65
       65
       +
       #### 2.2 自定义类型处理器

     

       66
       66
       +
       

     

       67
       67
       +
       - **LexiconRef**: 处理跨定义引用解析

     

       68
       68
       +
       - **LexiconUnion**: 处理联合类型验证

     

       69
       69
       +
       - **LexiconToken**: 处理符号化值

     

       70
       70
       +
       - **RecordModel**: 记录类型基类

     

       71
       71
       +
       - **QueryModel**: 查询类型基类

     

       72
       72
       +
       

     

       73
       73
       +
       ### 3. 模型生成系统

     

       74
       74
       +
       

     

       75
       75
       +
       #### 3.1 动态模型生成

     

       76
       76
       +
       

     

       77
       77
       +
       ```python

     

       78
       78
       +
       class ModelGenerator:

     

       79
       79
       +
           """动态生成 Pydantic 模型"""

     

       80
       80
       +
           

     

       81
       81
       +
           def generate_record_model(self, definition: dict) -> Type[BaseModel]:

     

       82
       82
       +
               """生成记录模型"""

     

       83
       83
       +
               pass

     

       84
       84
       +
           

     

       85
       85
       +
           def generate_query_model(self, definition: dict) -> Type[BaseModel]:

     

       86
       86
       +
               """生成查询模型"""

     

       87
       87
       +
               pass

     

       88
       88
       +
           

     

       89
       89
       +
           def generate_field_validator(self, field_def: dict) -> Callable:

     

       90
       90
       +
               """生成字段验证器"""

     

       91
       91
       +
               pass

     

       92
       92
       +
       ```

     

       93
       93
       +
       

     

       94
       94
       +
       #### 3.2 约束处理

     

       95
       95
       +
       

     

       96
       96
       +
       ```python

     

       97
       97
       +
       class ConstraintProcessor:

     

       98
       98
       +
           """处理字段约束"""

     

       99
       99
       +
           

     

       100
       100
       +
           def process_integer_constraints(self, field_def: dict) -> dict:

     

       101
       101
       +
               """处理整数约束 (min, max, enum)"""

     

       102
       102
       +
               pass

     

       103
       103
       +
           

     

       104
       104
       +
           def process_string_constraints(self, field_def: dict) -> dict:

     

       105
       105
       +
               """处理字符串约束 (format, length, enum)"""

     

       106
       106
       +
               pass

     

       107
       107
       +
           

     

       108
       108
       +
           def process_array_constraints(self, field_def: dict) -> dict:

     

       109
       109
       +
               """处理数组约束 (minLength, maxLength)"""

     

       110
       110
       +
               pass

     

       111
       111
       +
       ```

     

       112
       112
       +
       

     

       113
       113
       +
       ### 4. 注册表和缓存机制

     

       114
       114
       +
       

     

       115
       115
       +
       #### 4.1 模型注册表

     

       116
       116
       +
       

     

       117
       117
       +
       ```python

     

       118
       118
       +
       class LexiconRegistry:

     

       119
       119
       +
           """Lexicon 模型注册表"""

     

       120
       120
       +
           

     

       121
       121
       +
           def __init__(self):

     

       122
       122
       +
               self._models: Dict[str, Type[BaseModel]] = {}

     

       123
       123
       +
               self._definitions: Dict[str, dict] = {}

     

       124
       124
       +
               self._ref_cache: Dict[str, Type[BaseModel]] = {}

     

       125
       125
       +
           

     

       126
       126
       +
           def register(self, nsid: str, model: Type[BaseModel], definition: dict):

     

       127
       127
       +
               """注册 Lexicon 模型"""

     

       128
       128
       +
               pass

     

       129
       129
       +
           

     

       130
       130
       +
           def get_model(self, nsid: str) -> Optional[Type[BaseModel]]:

     

       131
       131
       +
               """获取已注册的模型"""

     

       132
       132
       +
               pass

     

       133
       133
       +
           

     

       134
       134
       +
           def resolve_ref(self, ref: str) -> Optional[Type[BaseModel]]:

     

       135
       135
       +
               """解析引用到具体模型"""

     

       136
       136
       +
               pass

     

       137
       137
       +
           

     

       138
       138
       +
           def clear_cache(self):

     

       139
       139
       +
               """清空缓存"""

     

       140
       140
       +
               pass

     

       141
       141
       +
       ```

     

       142
       142
       +
       

     

       143
       143
       +
       #### 4.2 缓存策略

     

       144
       144
       +
       

     

       145
       145
       +
       - **内存缓存**: 缓存已解析的模型定义

     

       146
       146
       +
       - **文件缓存**: 缓存序列化结果以提高性能

     

       147
       147
       +
       - **LRU 策略**: 使用最近最少使用算法管理缓存

     

       148
       148
       +
       

     

       149
       149
       +
       ### 5. 验证系统

     

       150
       150
       +
       

     

       151
       151
       +
       #### 5.1 验证层级

     

       152
       152
       +
       

     

       153
       153
       +
       1. **语法验证**: JSON Schema 结构验证

     

       154
       154
       +
       2. **语义验证**: 类型约束和业务规则验证

     

       155
       155
       +
       3. **引用验证**: 跨定义引用有效性验证

     

       156
       156
       +
       4. **兼容性验证**: 前向和后向兼容性检查

     

       157
       157
       +
       

     

       158
       158
       +
       #### 5.2 自定义验证器

     

       159
       159
       +
       

     

       160
       160
       +
       ```python

     

       161
       161
       +
       class LexiconValidator:

     

       162
       162
       +
           """Lexicon 定义验证器"""

     

       163
       163
       +
           

     

       164
       164
       +
           def validate_definition(self, definition: dict) -> bool:

     

       165
       165
       +
               """验证 Lexicon 定义完整性"""

     

       166
       166
       +
               pass

     

       167
       167
       +
           

     

       168
       168
       +
           def validate_refs(self, definition: dict) -> List[str]:

     

       169
       169
       +
               """验证所有引用的有效性"""

     

       170
       170
       +
               pass

     

       171
       171
       +
           

     

       172
       172
       +
           def validate_compatibility(self, old_def: dict, new_def: dict) -> bool:

     

       173
       173
       +
               """验证版本兼容性"""

     

       174
       174
       +
               pass

     

       175
       175
       +
       ```

     

       176
       176
       +
       

     

       177
       177
       +
       ### 6. 错误处理系统

     

       178
       178
       +
       

     

       179
       179
       +
       #### 6.1 错误类型体系

     

       180
       180
       +
       

     

       181
       181
       +
       ```python

     

       182
       182
       +
       class LexiconError(Exception):

     

       183
       183
       +
           """基础 Lexicon 错误"""

     

       184
       184
       +
           pass

     

       185
       185
       +
       

     

       186
       186
       +
       class ParseError(LexiconError):

     

       187
       187
       +
           """解析错误"""

     

       188
       188
       +
           pass

     

       189
       189
       +
       

     

       190
       190
       +
       class ValidationError(LexiconError):

     

       191
       191
       +
           """验证错误"""

     

       192
       192
       +
           pass

     

       193
       193
       +
       

     

       194
       194
       +
       class ResolutionError(LexiconError):

     

       195
       195
       +
           """引用解析错误"""

     

       196
       196
       +
           pass

     

       197
       197
       +
       

     

       198
       198
       +
       class GenerationError(LexiconError):

     

       199
       199
       +
           """模型生成错误"""

     

       200
       200
       +
           pass

     

       201
       201
       +
       ```

     

       202
       202
       +
       

     

       203
       203
       +
       #### 6.2 诊断信息

     

       204
       204
       +
       

     

       205
       205
       +
       - **详细错误消息**: 包含具体的字段路径和期望值

     

       206
       206
       +
       - **上下文信息**: 提供验证时的上下文信息

     

       207
       207
       +
       - **建议修复**: 提供可能的修复建议

     

       208
       208
       +
       

     

       209
       209
       +
       ### 7. 模块文件结构

     

       210
       210
       +
       

     

       211
       211
       +
       ```

     

       212
       212
       +
       src/atpasser/lexicon/

     

       213
       213
       +
       ├── __init__.py              # 模块导出

     

       214
       214
       +
       ├── ARCHITECTURE.md          # 架构文档

     

       215
       215
       +
       ├── parser.py                # 主解析器

     

       216
       216
       +
       ├── generator.py             # 模型生成器

     

       217
       217
       +
       ├── registry.py              # 注册表实现

     

       218
       218
       +
       ├── validator.py             # 验证器实现

     

       219
       219
       +
       ├── types.py                 # 类型定义

     

       220
       220
       +
       ├── exceptions.py            # 异常定义

     

       221
       221
       +
       ├── constraints.py           # 约束处理器

     

       222
       222
       +
       └── utils.py                 # 工具函数

     

       223
       223
       +
       ```

     

       224
       224
       +
       

     

       225
       225
       +
       ### 8. 依赖关系

     

       226
       226
       +
       

     

       227
       227
       +
       - **内部依赖**: 

     

       228
       228
       +
         - `src/atpasser/data` (数据序列化和验证)

     

       229
       229
       +
         - `src/atpasser/uri` (NSID 验证和处理)

     

       230
       230
       +
       - **外部依赖**:

     

       231
       231
       +
         - `pydantic`: 模型生成和验证

     

       232
       232
       +
         - `jsonpath-ng`: JSONPath 支持

     

       233
       233
       +
         - `cbor2`: CBOR 序列化支持

     

       234
       234
       +
       

     

       235
       235
       +
       ## 实现策略

     

       236
       236
       +
       

     

       237
       237
       +
       ### 1. 渐进式实现

     

       238
       238
       +
       

     

       239
       239
       +
       1. **阶段一**: 实现基础解析器和简单类型映射

     

       240
       240
       +
       2. **阶段二**: 添加复杂类型和引用解析

     

       241
       241
       +
       3. **阶段三**: 实现模型生成和注册表

     

       242
       242
       +
       4. **阶段四**: 添加高级验证和错误处理

     

       243
       243
       +
       

     

       244
       244
       +
       ### 2. 测试策略

     

       245
       245
       +
       

     

       246
       246
       +
       - **单元测试**: 测试各个解析器组件

     

       247
       247
       +
       - **集成测试**: 测试端到端 Lexicon 解析流程

     

       248
       248
       +
       - **兼容性测试**: 确保与现有 Lexicon 文件兼容

     

       249
       249
       +
       - **性能测试**: 验证解析和模型生成性能

     

       250
       250
       +
       

     

       251
       251
       +
       ### 3. 扩展性考虑

     

       252
       252
       +
       

     

       253
       253
       +
       - **插件系统**: 支持自定义类型解析器

     

       254
       254
       +
       - **中间件**: 支持预处理和后处理钩子

     

       255
       255
       +
       - **监控**: 集成性能监控和日志记录

     

       256
       256
       +
       

     

       257
       257
       +
       ## 优势

     

       258
       258
       +
       

     

       259
       259
       +
       1. **类型安全**: 利用 Pydantic 的强类型系统

     

       260
       260
       +
       2. **性能**: 优化的解析和缓存机制

     

       261
       261
       +
       3. **可扩展**: 模块化设计支持未来扩展

     

       262
       262
       +
       4. **兼容性**: 保持与 ATProto Lexicon 规范完全兼容

     

       263
       263
       +
       5. **开发者友好**: 提供清晰的错误消息和文档

+71

src/atpasser/lexicon/__init__.py

···

       1
       1
       +
       """ATProto Lexicon module for parsing and managing schema definitions."""

     

       2
       2
       +
       

     

       3
       3
       +
       from .exceptions import (

     

       4
       4
       +
           LexiconError,

     

       5
       5
       +
           ParseError,

     

       6
       6
       +
           ValidationError,

     

       7
       7
       +
           ResolutionError,

     

       8
       8
       +
           GenerationError,

     

       9
       9
       +
           CompatibilityError,

     

       10
       10
       +
       )

     

       11
       11
       +
       

     

       12
       12
       +
       from .types import (

     

       13
       13
       +
           LexiconType,

     

       14
       14
       +
           LexiconDefinition,

     

       15
       15
       +
           IntegerConstraints,

     

       16
       16
       +
           StringConstraints,

     

       17
       17
       +
           ArrayConstraints,

     

       18
       18
       +
           ObjectConstraints,

     

       19
       19
       +
           BlobConstraints,

     

       20
       20
       +
           ParamsConstraints,

     

       21
       21
       +
           RefDefinition,

     

       22
       22
       +
           UnionDefinition,

     

       23
       23
       +
           RecordDefinition,

     

       24
       24
       +
           QueryDefinition,

     

       25
       25
       +
           ProcedureDefinition,

     

       26
       26
       +
           SubscriptionDefinition,

     

       27
       27
       +
           LexiconDocument,

     

       28
       28
       +
           ErrorDefinition,

     

       29
       29
       +
           LexiconSchema,

     

       30
       30
       +
           PropertyMap,

     

       31
       31
       +
           DefinitionMap,

     

       32
       32
       +
       )

     

       33
       33
       +
       

     

       34
       34
       +
       from .registry import LexiconRegistry, registry

     

       35
       35
       +
       from .parser import LexiconParser, parser

     

       36
       36
       +
       

     

       37
       37
       +
       __all__ = [

     

       38
       38
       +
           # Exceptions

     

       39
       39
       +
           "LexiconError",

     

       40
       40
       +
           "ParseError",

     

       41
       41
       +
           "ValidationError",

     

       42
       42
       +
           "ResolutionError",

     

       43
       43
       +
           "GenerationError",

     

       44
       44
       +
           "CompatibilityError",

     

       45
       45
       +
           # Types

     

       46
       46
       +
           "LexiconType",

     

       47
       47
       +
           "LexiconDefinition",

     

       48
       48
       +
           "IntegerConstraints",

     

       49
       49
       +
           "StringConstraints",

     

       50
       50
       +
           "ArrayConstraints",

     

       51
       51
       +
           "ObjectConstraints",

     

       52
       52
       +
           "BlobConstraints",

     

       53
       53
       +
           "ParamsConstraints",

     

       54
       54
       +
           "RefDefinition",

     

       55
       55
       +
           "UnionDefinition",

     

       56
       56
       +
           "RecordDefinition",

     

       57
       57
       +
           "QueryDefinition",

     

       58
       58
       +
           "ProcedureDefinition",

     

       59
       59
       +
           "SubscriptionDefinition",

     

       60
       60
       +
           "LexiconDocument",

     

       61
       61
       +
           "ErrorDefinition",

     

       62
       62
       +
           "LexiconSchema",

     

       63
       63
       +
           "PropertyMap",

     

       64
       64
       +
           "DefinitionMap",

     

       65
       65
       +
           # Registry

     

       66
       66
       +
           "LexiconRegistry",

     

       67
       67
       +
           "registry",

     

       68
       68
       +
           # Parser

     

       69
       69
       +
           "LexiconParser",

     

       70
       70
       +
           "parser",

     

       71
       71
       +
       ]

+125

src/atpasser/lexicon/exceptions.py

···

       1
       1
       +
       """Exceptions for ATProto Lexicon module."""

     

       2
       2
       +
       

     

       3
       3
       +
       from typing import Optional

     

       4
       4
       +
       

     

       5
       5
       +
       

     

       6
       6
       +
       class LexiconError(Exception):

     

       7
       7
       +
           """Base exception for Lexicon errors."""

     

       8
       8
       +
       

     

       9
       9
       +
           def __init__(self, message: str, details: Optional[str] = None):

     

       10
       10
       +
               self.message = message

     

       11
       11
       +
               self.details = details

     

       12
       12
       +
               super().__init__(message)

     

       13
       13
       +
       

     

       14
       14
       +
       

     

       15
       15
       +
       class ParseError(LexiconError):

     

       16
       16
       +
           """Raised when Lexicon parsing fails."""

     

       17
       17
       +
       

     

       18
       18
       +
           def __init__(

     

       19
       19
       +
               self, message: str, nsid: Optional[str] = None, definition: Optional[str] = None

     

       20
       20
       +
           ):

     

       21
       21
       +
               self.nsid = nsid

     

       22
       22
       +
               self.definition = definition

     

       23
       23
       +
       

     

       24
       24
       +
               details = []

     

       25
       25
       +
               if nsid:

     

       26
       26
       +
                   details.append(f"NSID: {nsid}")

     

       27
       27
       +
               if definition:

     

       28
       28
       +
                   details.append(f"Definition: {definition}")

     

       29
       29
       +
       

     

       30
       30
       +
               super().__init__(

     

       31
       31
       +
                   f"Parse error: {message}", "; ".join(details) if details else None

     

       32
       32
       +
               )

     

       33
       33
       +
       

     

       34
       34
       +
       

     

       35
       35
       +
       class ValidationError(LexiconError):

     

       36
       36
       +
           """Raised when Lexicon validation fails."""

     

       37
       37
       +
       

     

       38
       38
       +
           def __init__(

     

       39
       39
       +
               self,

     

       40
       40
       +
               message: str,

     

       41
       41
       +
               nsid: Optional[str] = None,

     

       42
       42
       +
               field: Optional[str] = None,

     

       43
       43
       +
               expected: Optional[str] = None,

     

       44
       44
       +
           ):

     

       45
       45
       +
               self.nsid = nsid

     

       46
       46
       +
               self.field = field

     

       47
       47
       +
               self.expected = expected

     

       48
       48
       +
       

     

       49
       49
       +
               details = []

     

       50
       50
       +
               if nsid:

     

       51
       51
       +
                   details.append(f"NSID: {nsid}")

     

       52
       52
       +
               if field:

     

       53
       53
       +
                   details.append(f"Field: {field}")

     

       54
       54
       +
               if expected:

     

       55
       55
       +
                   details.append(f"Expected: {expected}")

     

       56
       56
       +
       

     

       57
       57
       +
               super().__init__(

     

       58
       58
       +
                   f"Validation error: {message}", "; ".join(details) if details else None

     

       59
       59
       +
               )

     

       60
       60
       +
       

     

       61
       61
       +
       

     

       62
       62
       +
       class ResolutionError(LexiconError):

     

       63
       63
       +
           """Raised when reference resolution fails."""

     

       64
       64
       +
       

     

       65
       65
       +
           def __init__(

     

       66
       66
       +
               self, message: str, ref: Optional[str] = None, context: Optional[str] = None

     

       67
       67
       +
           ):

     

       68
       68
       +
               self.ref = ref

     

       69
       69
       +
               self.context = context

     

       70
       70
       +
       

     

       71
       71
       +
               details = []

     

       72
       72
       +
               if ref:

     

       73
       73
       +
                   details.append(f"Reference: {ref}")

     

       74
       74
       +
               if context:

     

       75
       75
       +
                   details.append(f"Context: {context}")

     

       76
       76
       +
       

     

       77
       77
       +
               super().__init__(

     

       78
       78
       +
                   f"Resolution error: {message}", "; ".join(details) if details else None

     

       79
       79
       +
               )

     

       80
       80
       +
       

     

       81
       81
       +
       

     

       82
       82
       +
       class GenerationError(LexiconError):

     

       83
       83
       +
           """Raised when model generation fails."""

     

       84
       84
       +
       

     

       85
       85
       +
           def __init__(

     

       86
       86
       +
               self,

     

       87
       87
       +
               message: str,

     

       88
       88
       +
               nsid: Optional[str] = None,

     

       89
       89
       +
               definition_type: Optional[str] = None,

     

       90
       90
       +
           ):

     

       91
       91
       +
               self.nsid = nsid

     

       92
       92
       +
               self.definitionType = definition_type

     

       93
       93
       +
       

     

       94
       94
       +
               details = []

     

       95
       95
       +
               if nsid:

     

       96
       96
       +
                   details.append(f"NSID: {nsid}")

     

       97
       97
       +
               if definition_type:

     

       98
       98
       +
                   details.append(f"Type: {definition_type}")

     

       99
       99
       +
       

     

       100
       100
       +
               super().__init__(

     

       101
       101
       +
                   f"Generation error: {message}", "; ".join(details) if details else None

     

       102
       102
       +
               )

     

       103
       103
       +
       

     

       104
       104
       +
       

     

       105
       105
       +
       class CompatibilityError(LexiconError):

     

       106
       106
       +
           """Raised when compatibility checks fail."""

     

       107
       107
       +
       

     

       108
       108
       +
           def __init__(

     

       109
       109
       +
               self,

     

       110
       110
       +
               message: str,

     

       111
       111
       +
               old_nsid: Optional[str] = None,

     

       112
       112
       +
               new_nsid: Optional[str] = None,

     

       113
       113
       +
           ):

     

       114
       114
       +
               self.oldNsid = old_nsid

     

       115
       115
       +
               self.newNsid = new_nsid

     

       116
       116
       +
       

     

       117
       117
       +
               details = []

     

       118
       118
       +
               if old_nsid:

     

       119
       119
       +
                   details.append(f"Old NSID: {old_nsid}")

     

       120
       120
       +
               if new_nsid:

     

       121
       121
       +
                   details.append(f"New NSID: {new_nsid}")

     

       122
       122
       +
       

     

       123
       123
       +
               super().__init__(

     

       124
       124
       +
                   f"Compatibility error: {message}", "; ".join(details) if details else None

     

       125
       125
       +
               )

+208

src/atpasser/lexicon/parser.py

···

       1
       1
       +
       """Parser for ATProto Lexicon definitions."""

     

       2
       2
       +
       

     

       3
       3
       +
       import json

     

       4
       4
       +
       from typing import Dict, Any, Optional, Type, Union

     

       5
       5
       +
       from pydantic import BaseModel, create_model

     

       6
       6
       +
       from .exceptions import ParseError, ValidationError

     

       7
       7
       +
       from .types import LexiconDocument, LexiconType

     

       8
       8
       +
       from .registry import registry

     

       9
       9
       +
       

     

       10
       10
       +
       

     

       11
       11
       +
       class LexiconParser:

     

       12
       12
       +
           """Parser for ATProto Lexicon JSON definitions."""

     

       13
       13
       +
       

     

       14
       14
       +
           def __init__(self):

     

       15
       15
       +
               self.validators = LexiconValidator()

     

       16
       16
       +
       

     

       17
       17
       +
           def parse_document(self, json_data: Union[str, dict]) -> LexiconDocument:

     

       18
       18
       +
               """Parse a Lexicon JSON document."""

     

       19
       19
       +
               try:

     

       20
       20
       +
                   if isinstance(json_data, str):

     

       21
       21
       +
                       data = json.loads(json_data)

     

       22
       22
       +
                   else:

     

       23
       23
       +
                       data = json_data

     

       24
       24
       +
       

     

       25
       25
       +
                   # Validate basic document structure

     

       26
       26
       +
                   self.validators.validate_document_structure(data)

     

       27
       27
       +
       

     

       28
       28
       +
                   # Parse into Pydantic model

     

       29
       29
       +
                   document = LexiconDocument.model_validate(data)

     

       30
       30
       +
       

     

       31
       31
       +
                   # Validate semantic rules

     

       32
       32
       +
                   self.validators.validate_document_semantics(document)

     

       33
       33
       +
       

     

       34
       34
       +
                   return document

     

       35
       35
       +
       

     

       36
       36
       +
               except Exception as e:

     

       37
       37
       +
                   if isinstance(e, (ParseError, ValidationError)):

     

       38
       38
       +
                       raise

     

       39
       39
       +
                   raise ParseError(f"Failed to parse Lexicon document: {str(e)}")

     

       40
       40
       +
       

     

       41
       41
       +
           def parse_and_register(self, json_data: Union[str, dict]) -> None:

     

       42
       42
       +
               """Parse a Lexicon document and register it."""

     

       43
       43
       +
               document = self.parse_document(json_data)

     

       44
       44
       +
               registry.register_lexicon(document)

     

       45
       45
       +
       

     

       46
       46
       +
               # Generate and register models for all definitions

     

       47
       47
       +
               generator = ModelGenerator()

     

       48
       48
       +
               for def_name, def_data in document.defs.items():

     

       49
       49
       +
                   try:

     

       50
       50
       +
                       model = generator.generate_model(document.id, def_name, def_data)

     

       51
       51
       +
                       registry.register_model(document.id, model, def_name)

     

       52
       52
       +
                   except Exception as e:

     

       53
       53
       +
                       raise ParseError(

     

       54
       54
       +
                           f"Failed to generate model for {def_name}: {str(e)}",

     

       55
       55
       +
                           document.id,

     

       56
       56
       +
                           def_name,

     

       57
       57
       +
                       )

     

       58
       58
       +
       

     

       59
       59
       +
       

     

       60
       60
       +
       class LexiconValidator:

     

       61
       61
       +
           """Validator for Lexicon documents."""

     

       62
       62
       +
       

     

       63
       63
       +
           def validate_document_structure(self, data: Dict[str, Any]) -> None:

     

       64
       64
       +
               """Validate basic document structure."""

     

       65
       65
       +
               required_fields = ["lexicon", "id", "defs"]

     

       66
       66
       +
               for field in required_fields:

     

       67
       67
       +
                   if field not in data:

     

       68
       68
       +
                       raise ValidationError(f"Missing required field: {field}")

     

       69
       69
       +
       

     

       70
       70
       +
               if not isinstance(data["defs"], dict) or not data["defs"]:

     

       71
       71
       +
                   raise ValidationError("defs must be a non-empty dictionary")

     

       72
       72
       +
       

     

       73
       73
       +
               if data["lexicon"] != 1:

     

       74
       74
       +
                   raise ValidationError("lexicon version must be 1")

     

       75
       75
       +
       

     

       76
       76
       +
           def validate_document_semantics(self, document: LexiconDocument) -> None:

     

       77
       77
       +
               """Validate semantic rules for Lexicon document."""

     

       78
       78
       +
               # Check primary type constraints

     

       79
       79
       +
               primary_types = {

     

       80
       80
       +
                   LexiconType.RECORD,

     

       81
       81
       +
                   LexiconType.QUERY,

     

       82
       82
       +
                   LexiconType.PROCEDURE,

     

       83
       83
       +
                   LexiconType.SUBSCRIPTION,

     

       84
       84
       +
               }

     

       85
       85
       +
       

     

       86
       86
       +
               primary_defs = []

     

       87
       87
       +
               for def_name, def_data in document.defs.items():

     

       88
       88
       +
                   def_type = def_data.get("type")

     

       89
       89
       +
                   if def_type in primary_types:

     

       90
       90
       +
                       primary_defs.append((def_name, def_type))

     

       91
       91
       +
       

     

       92
       92
       +
                       # Primary types should usually be named 'main'

     

       93
       93
       +
                       if def_name != "main":

     

       94
       94
       +
                           # This is a warning, not an error

     

       95
       95
       +
                           pass

     

       96
       96
       +
       

     

       97
       97
       +
               # Only one primary type allowed per document

     

       98
       98
       +
               if len(primary_defs) > 1:

     

       99
       99
       +
                   raise ValidationError(

     

       100
       100
       +
                       f"Multiple primary types found: {[name for name, _ in primary_defs]}",

     

       101
       101
       +
                       document.id,

     

       102
       102
       +
                   )

     

       103
       103
       +
       

     

       104
       104
       +
       

     

       105
       105
       +
       class ModelGenerator:

     

       106
       106
       +
           """Generates Pydantic models from Lexicon definitions."""

     

       107
       107
       +
       

     

       108
       108
       +
           def generate_model(

     

       109
       109
       +
               self, nsid: str, def_name: str, definition: Dict[str, Any]

     

       110
       110
       +
           ) -> Type[BaseModel]:

     

       111
       111
       +
               """Generate a Pydantic model from a Lexicon definition."""

     

       112
       112
       +
               def_type = definition.get("type")

     

       113
       113
       +
       

     

       114
       114
       +
               if def_type == LexiconType.RECORD:

     

       115
       115
       +
                   return self._generate_record_model(nsid, def_name, definition)

     

       116
       116
       +
               elif def_type == LexiconType.OBJECT:

     

       117
       117
       +
                   return self._generate_object_model(nsid, def_name, definition)

     

       118
       118
       +
               elif def_type in [

     

       119
       119
       +
                   LexiconType.QUERY,

     

       120
       120
       +
                   LexiconType.PROCEDURE,

     

       121
       121
       +
                   LexiconType.SUBSCRIPTION,

     

       122
       122
       +
               ]:

     

       123
       123
       +
                   return self._generate_primary_model(nsid, def_name, definition)

     

       124
       124
       +
               else:

     

       125
       125
       +
                   # For simple types, create a basic model

     

       126
       126
       +
                   return self._generate_simple_model(nsid, def_name, definition)

     

       127
       127
       +
       

     

       128
       128
       +
           def _generate_record_model(

     

       129
       129
       +
               self, nsid: str, def_name: str, definition: Dict[str, Any]

     

       130
       130
       +
           ) -> Type[BaseModel]:

     

       131
       131
       +
               """Generate a model for record type."""

     

       132
       132
       +
               record_schema = definition.get("record", {})

     

       133
       133
       +
               return self._generate_object_model(nsid, def_name, record_schema)

     

       134
       134
       +
       

     

       135
       135
       +
           def _generate_object_model(

     

       136
       136
       +
               self, nsid: str, def_name: str, definition: Dict[str, Any]

     

       137
       137
       +
           ) -> Type[BaseModel]:

     

       138
       138
       +
               """Generate a model for object type."""

     

       139
       139
       +
               properties = definition.get("properties", {})

     

       140
       140
       +
               required = definition.get("required", [])

     

       141
       141
       +
       

     

       142
       142
       +
               field_definitions = {}

     

       143
       143
       +
               for prop_name, prop_schema in properties.items():

     

       144
       144
       +
                   field_type = self._get_field_type(prop_schema)

     

       145
       145
       +
                   field_definitions[prop_name] = (

     

       146
       146
       +
                       field_type,

     

       147
       147
       +
                       ... if prop_name in required else None,

     

       148
       148
       +
                   )

     

       149
       149
       +
       

     

       150
       150
       +
               model_name = self._get_model_name(nsid, def_name)

     

       151
       151
       +
               return create_model(model_name, **field_definitions)

     

       152
       152
       +
       

     

       153
       153
       +
           def _generate_primary_model(

     

       154
       154
       +
               self, nsid: str, def_name: str, definition: Dict[str, Any]

     

       155
       155
       +
           ) -> Type[BaseModel]:

     

       156
       156
       +
               """Generate a model for primary types (query, procedure, subscription)."""

     

       157
       157
       +
               # For now, create a basic model - specific handling can be added later

     

       158
       158
       +
               return self._generate_simple_model(nsid, def_name, definition)

     

       159
       159
       +
       

     

       160
       160
       +
           def _generate_simple_model(

     

       161
       161
       +
               self, nsid: str, def_name: str, definition: Dict[str, Any]

     

       162
       162
       +
           ) -> Type[BaseModel]:

     

       163
       163
       +
               """Generate a simple model for basic types."""

     

       164
       164
       +
               field_type = self._get_field_type(definition)

     

       165
       165
       +
               model_name = self._get_model_name(nsid, def_name)

     

       166
       166
       +
               return create_model(model_name, value=(field_type, ...))

     

       167
       167
       +
       

     

       168
       168
       +
           def _get_field_type(self, schema: Dict[str, Any]) -> Any:

     

       169
       169
       +
               """Get the Python type for a schema definition."""

     

       170
       170
       +
               schema_type = schema.get("type")

     

       171
       171
       +
       

     

       172
       172
       +
               type_mapping = {

     

       173
       173
       +
                   LexiconType.NULL: type(None),

     

       174
       174
       +
                   LexiconType.BOOLEAN: bool,

     

       175
       175
       +
                   LexiconType.INTEGER: int,

     

       176
       176
       +
                   LexiconType.STRING: str,

     

       177
       177
       +
                   LexiconType.BYTES: bytes,

     

       178
       178
       +
                   LexiconType.ARRAY: list,

     

       179
       179
       +
                   LexiconType.OBJECT: dict,

     

       180
       180
       +
               }

     

       181
       181
       +
       

     

       182
       182
       +
               if schema_type and schema_type in type_mapping:

     

       183
       183
       +
                   return type_mapping[schema_type]

     

       184
       184
       +
       

     

       185
       185
       +
               if schema_type == LexiconType.REF:

     

       186
       186
       +
                   ref = schema.get("ref")

     

       187
       187
       +
                   if ref:

     

       188
       188
       +
                       return registry.resolve_ref(ref)

     

       189
       189
       +
       

     

       190
       190
       +
               # Default to Any for complex types

     

       191
       191
       +
               return Any

     

       192
       192
       +
       

     

       193
       193
       +
           def _get_model_name(self, nsid: str, def_name: str) -> str:

     

       194
       194
       +
               """Generate a valid Python class name from NSID and definition name."""

     

       195
       195
       +
               # Convert NSID to PascalCase

     

       196
       196
       +
               parts = nsid.split(".")

     

       197
       197
       +
               name_parts = [part.capitalize() for part in parts]

     

       198
       198
       +
       

     

       199
       199
       +
               # Add definition name

     

       200
       200
       +
               if def_name != "main":

     

       201
       201
       +
                   def_part = def_name.capitalize()

     

       202
       202
       +
                   name_parts.append(def_part)

     

       203
       203
       +
       

     

       204
       204
       +
               return "".join(name_parts)

     

       205
       205
       +
       

     

       206
       206
       +
       

     

       207
       207
       +
       # Global parser instance

     

       208
       208
       +
       parser = LexiconParser()

+114

src/atpasser/lexicon/registry.py

···

       1
       1
       +
       """Registry for managing Lexicon definitions and generated models."""

     

       2
       2
       +
       

     

       3
       3
       +
       from typing import Dict, Optional, Type, Any

     

       4
       4
       +
       from pydantic import BaseModel

     

       5
       5
       +
       from .exceptions import ResolutionError

     

       6
       6
       +
       from .types import LexiconDocument

     

       7
       7
       +
       

     

       8
       8
       +
       

     

       9
       9
       +
       class LexiconRegistry:

     

       10
       10
       +
           """Registry for storing and resolving Lexicon definitions and models."""

     

       11
       11
       +
       

     

       12
       12
       +
           def __init__(self):

     

       13
       13
       +
               self._definitions: Dict[str, LexiconDocument] = {}

     

       14
       14
       +
               self._models: Dict[str, Type[BaseModel]] = {}

     

       15
       15
       +
               self._ref_cache: Dict[str, Type[BaseModel]] = {}

     

       16
       16
       +
       

     

       17
       17
       +
           def register_lexicon(self, document: LexiconDocument) -> None:

     

       18
       18
       +
               """Register a Lexicon document."""

     

       19
       19
       +
               nsid = document.id

     

       20
       20
       +
               if nsid in self._definitions:

     

       21
       21
       +
                   raise ValueError(f"Lexicon with NSID {nsid} is already registered")

     

       22
       22
       +
       

     

       23
       23
       +
               self._definitions[nsid] = document

     

       24
       24
       +
       

     

       25
       25
       +
               # Clear cache for this NSID

     

       26
       26
       +
               self._clear_cache_for_nsid(nsid)

     

       27
       27
       +
       

     

       28
       28
       +
           def get_lexicon(self, nsid: str) -> Optional[LexiconDocument]:

     

       29
       29
       +
               """Get a registered Lexicon document by NSID."""

     

       30
       30
       +
               return self._definitions.get(nsid)

     

       31
       31
       +
       

     

       32
       32
       +
           def register_model(

     

       33
       33
       +
               self, nsid: str, model: Type[BaseModel], definition_name: Optional[str] = None

     

       34
       34
       +
           ) -> None:

     

       35
       35
       +
               """Register a generated model for a Lexicon definition."""

     

       36
       36
       +
               key = self._get_model_key(nsid, definition_name)

     

       37
       37
       +
               self._models[key] = model

     

       38
       38
       +
       

     

       39
       39
       +
               # Also cache for quick reference resolution

     

       40
       40
       +
               if definition_name and definition_name != "main":

     

       41
       41
       +
                   ref_key = f"{nsid}#{definition_name}"

     

       42
       42
       +
                   self._ref_cache[ref_key] = model

     

       43
       43
       +
       

     

       44
       44
       +
           def get_model(

     

       45
       45
       +
               self, nsid: str, definition_name: Optional[str] = None

     

       46
       46
       +
           ) -> Optional[Type[BaseModel]]:

     

       47
       47
       +
               """Get a registered model by NSID and optional definition name."""

     

       48
       48
       +
               key = self._get_model_key(nsid, definition_name)

     

       49
       49
       +
               return self._models.get(key)

     

       50
       50
       +
       

     

       51
       51
       +
           def resolve_ref(self, ref: str) -> Type[BaseModel]:

     

       52
       52
       +
               """Resolve a reference to a model."""

     

       53
       53
       +
               if ref in self._ref_cache:

     

       54
       54
       +
                   return self._ref_cache[ref]

     

       55
       55
       +
       

     

       56
       56
       +
               # Parse the reference

     

       57
       57
       +
               if "#" in ref:

     

       58
       58
       +
                   nsid, definition_name = ref.split("#", 1)

     

       59
       59
       +
               else:

     

       60
       60
       +
                   nsid, definition_name = ref, "main"

     

       61
       61
       +
       

     

       62
       62
       +
               model = self.get_model(nsid, definition_name)

     

       63
       63
       +
               if model is None:

     

       64
       64
       +
                   raise ResolutionError(f"Reference not found: {ref}", ref)

     

       65
       65
       +
       

     

       66
       66
       +
               # Cache for future use

     

       67
       67
       +
               self._ref_cache[ref] = model

     

       68
       68
       +
               return model

     

       69
       69
       +
       

     

       70
       70
       +
           def has_lexicon(self, nsid: str) -> bool:

     

       71
       71
       +
               """Check if a Lexicon is registered."""

     

       72
       72
       +
               return nsid in self._definitions

     

       73
       73
       +
       

     

       74
       74
       +
           def has_model(self, nsid: str, definition_name: Optional[str] = None) -> bool:

     

       75
       75
       +
               """Check if a model is registered."""

     

       76
       76
       +
               key = self._get_model_key(nsid, definition_name)

     

       77
       77
       +
               return key in self._models

     

       78
       78
       +
       

     

       79
       79
       +
           def clear_cache(self) -> None:

     

       80
       80
       +
               """Clear all cached models and references."""

     

       81
       81
       +
               self._models.clear()

     

       82
       82
       +
               self._ref_cache.clear()

     

       83
       83
       +
       

     

       84
       84
       +
           def _get_model_key(self, nsid: str, definition_name: Optional[str]) -> str:

     

       85
       85
       +
               """Get the internal key for model storage."""

     

       86
       86
       +
               if definition_name:

     

       87
       87
       +
                   return f"{nsid}#{definition_name}"

     

       88
       88
       +
               return f"{nsid}#main"

     

       89
       89
       +
       

     

       90
       90
       +
           def _clear_cache_for_nsid(self, nsid: str) -> None:

     

       91
       91
       +
               """Clear cache entries for a specific NSID."""

     

       92
       92
       +
               # Clear models

     

       93
       93
       +
               keys_to_remove = [

     

       94
       94
       +
                   key for key in self._models.keys() if key.startswith(f"{nsid}#")

     

       95
       95
       +
               ]

     

       96
       96
       +
               for key in keys_to_remove:

     

       97
       97
       +
                   del self._models[key]

     

       98
       98
       +
       

     

       99
       99
       +
               # Clear ref cache

     

       100
       100
       +
               keys_to_remove = [key for key in self._ref_cache.keys() if key.startswith(nsid)]

     

       101
       101
       +
               for key in keys_to_remove:

     

       102
       102
       +
                   del self._ref_cache[key]

     

       103
       103
       +
       

     

       104
       104
       +
           def list_lexicons(self) -> Dict[str, LexiconDocument]:

     

       105
       105
       +
               """List all registered Lexicon documents."""

     

       106
       106
       +
               return self._definitions.copy()

     

       107
       107
       +
       

     

       108
       108
       +
           def list_models(self) -> Dict[str, Type[BaseModel]]:

     

       109
       109
       +
               """List all registered models."""

     

       110
       110
       +
               return self._models.copy()

     

       111
       111
       +
       

     

       112
       112
       +
       

     

       113
       113
       +
       # Global registry instance

     

       114
       114
       +
       registry = LexiconRegistry()

+155

src/atpasser/lexicon/types.py

···

       1
       1
       +
       """Type definitions for ATProto Lexicon module."""

     

       2
       2
       +
       

     

       3
       3
       +
       from typing import Dict, List, Optional, Union, Any, Type

     

       4
       4
       +
       from enum import Enum

     

       5
       5
       +
       from pydantic import BaseModel, Field

     

       6
       6
       +
       

     

       7
       7
       +
       

     

       8
       8
       +
       class LexiconType(str, Enum):

     

       9
       9
       +
           """Enumeration of Lexicon definition types."""

     

       10
       10
       +
       

     

       11
       11
       +
           NULL = "null"

     

       12
       12
       +
           BOOLEAN = "boolean"

     

       13
       13
       +
           INTEGER = "integer"

     

       14
       14
       +
           STRING = "string"

     

       15
       15
       +
           BYTES = "bytes"

     

       16
       16
       +
           CID_LINK = "cid-link"

     

       17
       17
       +
           BLOB = "blob"

     

       18
       18
       +
           ARRAY = "array"

     

       19
       19
       +
           OBJECT = "object"

     

       20
       20
       +
           PARAMS = "params"

     

       21
       21
       +
           TOKEN = "token"

     

       22
       22
       +
           REF = "ref"

     

       23
       23
       +
           UNION = "union"

     

       24
       24
       +
           UNKNOWN = "unknown"

     

       25
       25
       +
           RECORD = "record"

     

       26
       26
       +
           QUERY = "query"

     

       27
       27
       +
           PROCEDURE = "procedure"

     

       28
       28
       +
           SUBSCRIPTION = "subscription"

     

       29
       29
       +
       

     

       30
       30
       +
       

     

       31
       31
       +
       class LexiconDefinition(BaseModel):

     

       32
       32
       +
           """Base class for Lexicon definitions."""

     

       33
       33
       +
       

     

       34
       34
       +
           type: LexiconType

     

       35
       35
       +
           description: Optional[str] = None

     

       36
       36
       +
       

     

       37
       37
       +
       

     

       38
       38
       +
       class IntegerConstraints(BaseModel):

     

       39
       39
       +
           """Constraints for integer fields."""

     

       40
       40
       +
       

     

       41
       41
       +
           minimum: Optional[int] = None

     

       42
       42
       +
           maximum: Optional[int] = None

     

       43
       43
       +
           enum: Optional[List[int]] = None

     

       44
       44
       +
           default: Optional[int] = None

     

       45
       45
       +
           const: Optional[int] = None

     

       46
       46
       +
       

     

       47
       47
       +
       

     

       48
       48
       +
       class StringConstraints(BaseModel):

     

       49
       49
       +
           """Constraints for string fields."""

     

       50
       50
       +
       

     

       51
       51
       +
           format: Optional[str] = None

     

       52
       52
       +
           maxLength: Optional[int] = None

     

       53
       53
       +
           minLength: Optional[int] = None

     

       54
       54
       +
           maxGraphemes: Optional[int] = None

     

       55
       55
       +
           minGraphemes: Optional[int] = None

     

       56
       56
       +
           knownValues: Optional[List[str]] = None

     

       57
       57
       +
           enum: Optional[List[str]] = None

     

       58
       58
       +
           default: Optional[str] = None

     

       59
       59
       +
           const: Optional[str] = None

     

       60
       60
       +
       

     

       61
       61
       +
       

     

       62
       62
       +
       class ArrayConstraints(BaseModel):

     

       63
       63
       +
           """Constraints for array fields."""

     

       64
       64
       +
       

     

       65
       65
       +
           items: Dict[str, Any]  # Schema definition for array items

     

       66
       66
       +
           minLength: Optional[int] = None

     

       67
       67
       +
           maxLength: Optional[int] = None

     

       68
       68
       +
       

     

       69
       69
       +
       

     

       70
       70
       +
       class ObjectConstraints(BaseModel):

     

       71
       71
       +
           """Constraints for object fields."""

     

       72
       72
       +
       

     

       73
       73
       +
           properties: Dict[str, Dict[str, Any]]  # Map of property names to schemas

     

       74
       74
       +
           required: Optional[List[str]] = None

     

       75
       75
       +
           nullable: Optional[List[str]] = None

     

       76
       76
       +
       

     

       77
       77
       +
       

     

       78
       78
       +
       class BlobConstraints(BaseModel):

     

       79
       79
       +
           """Constraints for blob fields."""

     

       80
       80
       +
       

     

       81
       81
       +
           accept: Optional[List[str]] = None  # MIME types

     

       82
       82
       +
           maxSize: Optional[int] = None  # Maximum size in bytes

     

       83
       83
       +
       

     

       84
       84
       +
       

     

       85
       85
       +
       class ParamsConstraints(BaseModel):

     

       86
       86
       +
           """Constraints for params fields."""

     

       87
       87
       +
       

     

       88
       88
       +
           properties: Dict[str, Dict[str, Any]]

     

       89
       89
       +
           required: Optional[List[str]] = None

     

       90
       90
       +
       

     

       91
       91
       +
       

     

       92
       92
       +
       class RefDefinition(BaseModel):

     

       93
       93
       +
           """Reference definition."""

     

       94
       94
       +
       

     

       95
       95
       +
           ref: str  # Reference to another schema

     

       96
       96
       +
       

     

       97
       97
       +
       

     

       98
       98
       +
       class UnionDefinition(BaseModel):

     

       99
       99
       +
           """Union type definition."""

     

       100
       100
       +
       

     

       101
       101
       +
           refs: List[str]  # List of references

     

       102
       102
       +
           closed: Optional[bool] = False  # Whether union is closed

     

       103
       103
       +
       

     

       104
       104
       +
       

     

       105
       105
       +
       class RecordDefinition(LexiconDefinition):

     

       106
       106
       +
           """Record type definition."""

     

       107
       107
       +
       

     

       108
       108
       +
           key: str  # Record key type

     

       109
       109
       +
           record: Dict[str, Any]  # Object schema

     

       110
       110
       +
       

     

       111
       111
       +
       

     

       112
       112
       +
       class QueryDefinition(LexiconDefinition):

     

       113
       113
       +
           """Query type definition."""

     

       114
       114
       +
       

     

       115
       115
       +
           parameters: Optional[Dict[str, Any]] = None  # Params schema

     

       116
       116
       +
           output: Optional[Dict[str, Any]] = None  # Output schema

     

       117
       117
       +
       

     

       118
       118
       +
       

     

       119
       119
       +
       class ProcedureDefinition(LexiconDefinition):

     

       120
       120
       +
           """Procedure type definition."""

     

       121
       121
       +
       

     

       122
       122
       +
           parameters: Optional[Dict[str, Any]] = None  # Params schema

     

       123
       123
       +
           input: Optional[Dict[str, Any]] = None  # Input schema

     

       124
       124
       +
           output: Optional[Dict[str, Any]] = None  # Output schema

     

       125
       125
       +
           errors: Optional[List[Dict[str, Any]]] = None  # Error definitions

     

       126
       126
       +
       

     

       127
       127
       +
       

     

       128
       128
       +
       class SubscriptionDefinition(LexiconDefinition):

     

       129
       129
       +
           """Subscription type definition."""

     

       130
       130
       +
       

     

       131
       131
       +
           parameters: Optional[Dict[str, Any]] = None  # Params schema

     

       132
       132
       +
           message: Optional[Dict[str, Any]] = None  # Message schema

     

       133
       133
       +
           errors: Optional[List[Dict[str, Any]]] = None  # Error definitions

     

       134
       134
       +
       

     

       135
       135
       +
       

     

       136
       136
       +
       class LexiconDocument(BaseModel):

     

       137
       137
       +
           """Complete Lexicon document."""

     

       138
       138
       +
       

     

       139
       139
       +
           lexicon: int  # Lexicon version (always 1)

     

       140
       140
       +
           id: str  # NSID of the Lexicon

     

       141
       141
       +
           description: Optional[str] = None

     

       142
       142
       +
           defs: Dict[str, Dict[str, Any]]  # Map of definition names to schemas

     

       143
       143
       +
       

     

       144
       144
       +
       

     

       145
       145
       +
       class ErrorDefinition(BaseModel):

     

       146
       146
       +
           """Error definition for procedures and subscriptions."""

     

       147
       147
       +
       

     

       148
       148
       +
           name: str  # Error name

     

       149
       149
       +
           description: Optional[str] = None

     

       150
       150
       +
       

     

       151
       151
       +
       

     

       152
       152
       +
       # Type aliases for convenience

     

       153
       153
       +
       LexiconSchema = Dict[str, Any]

     

       154
       154
       +
       PropertyMap = Dict[str, LexiconSchema]

     

       155
       155
       +
       DefinitionMap = Dict[str, Union[LexiconDefinition, Dict[str, Any]]]

Compare changes