podns 0.1.1__py3-none-any.whl

podns/__init__.py

@@ -0,0 +1,37 @@
+"""
+MIT License
+
+Copyright (c) 2024-present abigail phoebe <abigail@phoebe.sh>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+
+from .dns import fetch_pronouns_from_domain_sync, fetch_pronouns_from_domain_async
+from .error import PODNSError
+from .parser import parse_pronoun_records
+from .pronouns import PronounsResponse
+
+
+__all__: tuple[str, ...] = (
+    "fetch_pronouns_from_domain_sync",
+    "fetch_pronouns_from_domain_async",
+    "PODNSError",
+    "parse_pronoun_records",
+    "PronounsResponse",
+)

podns/dns.py

@@ -0,0 +1,51 @@
+"""
+MIT License
+
+Copyright (c) 2024-present abigail phoebe <abigail@phoebe.sh>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+
+import dns.asyncresolver
+import dns.resolver
+
+from podns.parser import parse_pronoun_records
+from podns.pronouns import PronounsResponse
+
+
+__all__: tuple[str, ...] = (
+    "fetch_pronouns_from_domain_sync",
+    "fetch_pronouns_from_domain_async",
+)
+
+
+def fetch_pronouns_from_domain_sync(domain: str, *, pedantic: bool = False) -> PronounsResponse | None:
+    try:
+        dns_answers = dns.resolver.resolve(f"pronouns.{domain}", "TXT")
+    except dns.resolver.NXDOMAIN:
+        return None
+    return parse_pronoun_records(list(dns_answers), pedantic=pedantic)
+
+
+async def fetch_pronouns_from_domain_async(domain: str, *, pedantic: bool = False) -> PronounsResponse | None:
+    try:
+        dns_answers = await dns.asyncresolver.resolve(f"pronouns.{domain}", "TXT")
+    except dns.resolver.NXDOMAIN:
+        return None
+    return parse_pronoun_records(list(dns_answers), pedantic=pedantic)

podns/error.py

@@ -0,0 +1,76 @@
+"""
+MIT License
+
+Copyright (c) 2024-present abigail phoebe <abigail@phoebe.sh>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+
+__all__: tuple[str, ...] = (
+    "PODNSError",
+    "PODNSParserError",
+    "PODNSParserSetsAfterNone",
+    "PODNSParserInvalidTag",
+    "PODNSParserEmptySegmentInPronounSet",
+    "PODNSParserTagWithoutPronounSet",
+    "PODNSParserTrailingSlash",
+    "PODNSParserInsufficientPronounSetValues",
+    "PODNSParserIllegalCharacterInPronouns",
+    "PODNSParserTooManyPronounSetValues",
+)
+
+
+class PODNSError(Exception):
+    pass
+
+
+class PODNSParserError(PODNSError):
+    pass
+
+
+class PODNSParserSetsAfterNone(PODNSParserError):
+    pass
+
+
+class PODNSParserInvalidTag(PODNSParserError):
+    pass
+
+
+class PODNSParserEmptySegmentInPronounSet(PODNSParserError):
+    pass
+
+
+class PODNSParserTagWithoutPronounSet(PODNSParserError):
+    pass
+
+
+class PODNSParserTrailingSlash(PODNSParserError):
+    pass
+
+
+class PODNSParserInsufficientPronounSetValues(PODNSParserError):
+    pass
+
+
+class PODNSParserIllegalCharacterInPronouns(PODNSParserError):
+    pass
+
+
+class PODNSParserTooManyPronounSetValues(PODNSParserError):
+    pass

podns/parser.py

@@ -0,0 +1,201 @@
+"""
+MIT License
+
+Copyright (c) 2024-present abigail phoebe <abigail@phoebe.sh>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+
+from typing import Final, Literal
+
+from podns.error import (
+    PODNSParserEmptySegmentInPronounSet,
+    PODNSParserIllegalCharacterInPronouns,
+    PODNSParserInsufficientPronounSetValues,
+    PODNSParserInvalidTag,
+    PODNSParserSetsAfterNone,
+    PODNSParserTagWithoutPronounSet,
+    PODNSParserTooManyPronounSetValues,
+    PODNSParserTrailingSlash,
+)
+from podns.pronouns import (
+    PronounRecord,
+    Pronouns,
+    PronounsResponse,
+    PronounTag,
+)
+
+
+__all__: tuple[str, ...] = (
+    "parse_pronoun_records",
+)
+
+
+ILLEGAL_PRONOUN_CHARACTERS: Final[Literal[r'*;/!#']] = r'*;/!#'
+PARSER_CONVERSIONS: Final[dict[str, str]] = {
+    "it/its": "it/it/its/its/itself",
+}
+
+
+def _normalise_record(record: str) -> str:
+    # remove comments, capitalisation and leading/trailing whitespace.
+    record = record.split("#")[0].lower().strip()
+
+    # remove spaces around /'s
+    pronoun_segment: str = record.split(";")[0]
+    pronoun_segments: list[str] = pronoun_segment.split("/")
+    pronoun_segment: str = '/'.join(seg.strip() for seg in pronoun_segments)
+
+    # ensure that there are no illegal characters present
+    illegal_characters_set: set[str] = set(ILLEGAL_PRONOUN_CHARACTERS)
+    for seg in pronoun_segments:
+        if illegal_characters_set.difference(seg) != illegal_characters_set:
+            raise PODNSParserIllegalCharacterInPronouns(f"{seg=} contains an illegal character defined by: {ILLEGAL_PRONOUN_CHARACTERS=}")
+
+    # add tag part back to record
+    tag_segment_parts: list[str] = record.split(";")
+    if len(tag_segment_parts) == 1:
+        full_record = pronoun_segment
+    else:
+        tag_segment: str = ';'.join(tag_segment_parts[1:])
+        full_record: str = pronoun_segment + ";" + tag_segment
+
+    # normalise repeating ;
+    _strip_chars: bool = False
+    stripped_record: str = ""
+    for char in full_record:
+        if char == ";" and not _strip_chars:
+            _strip_chars = True
+            stripped_record += char
+        elif char != ";" and _strip_chars:
+            _strip_chars = False
+            stripped_record += char
+        elif not _strip_chars:
+            stripped_record += char
+
+    return stripped_record
+
+
+def _parse_pronouns(record, *, pedantic: bool) -> Pronouns:
+    # we do not care about the tag section here.
+    pronoun_part = record.split(";")[0]
+
+    if pronoun_part in PARSER_CONVERSIONS.keys():
+        pronoun_part = PARSER_CONVERSIONS[pronoun_part]
+
+    # check for trailing slash
+    if pronoun_part.endswith("/") and pedantic:
+        raise PODNSParserTrailingSlash(f"Trailing slash in pronouns with {pedantic=} - {record=}")
+
+    # check for empty segment
+    pronouns_set = pronoun_part.split("/")
+    if any(True for p in pronouns_set if len(p) == 0):
+        raise PODNSParserEmptySegmentInPronounSet(f"Empty pronoun segment: {record=}")
+
+    # ensure at least subject/object are present
+    if len(pronouns_set) < 2:
+        raise PODNSParserInsufficientPronounSetValues(f"There must be at least subject and object pronouns: {record=}")
+
+    if len(pronouns_set) > 5 and pedantic:
+        raise PODNSParserTooManyPronounSetValues(f"There are too many provided pronoun values: {record=}")
+
+    # appropriately parse into a `Pronouns` object
+    possessive_determiner = None
+    if len(pronouns_set) > 2:
+        possessive_determiner = pronouns_set[2]
+
+    possessive_pronoun = None
+    if len(pronouns_set) > 3:
+        possessive_pronoun = pronouns_set[3]
+
+    reflexive = None
+    if len(pronouns_set) > 4:
+        reflexive = pronouns_set[4]
+
+    return Pronouns(
+        subject=pronouns_set[0],
+        object=pronouns_set[1],
+        possessive_determiner=possessive_determiner,
+        possessive_pronoun=possessive_pronoun,
+        reflexive=reflexive,
+    )
+
+
+def _parse_tags(record, *, pedantic: bool) -> set[PronounTag]:
+    parts = record.rsplit(";")
+    if len(parts) == 1 and ";" in record:
+        if pedantic:
+            raise PODNSParserTagWithoutPronounSet(f"A tag was defined without a preceding pronoun set declaration: {record=}")
+        else:
+            return set()
+
+    pronoun_tags: set[PronounTag] = set()
+    parsed_tags = set(parts[1:]).difference("")
+    for parsed_tag in parsed_tags:
+        try:
+            pronoun_tags.add(PronounTag(parsed_tag))
+        except ValueError:
+            if pedantic:
+                raise PODNSParserInvalidTag(f"Invalid tag: {parsed_tag=}")
+
+    return pronoun_tags
+
+
+def _parse_record(record: str, *, pedantic: bool) -> PronounRecord:
+    # parse the pronouns and tags part into an appropriate record
+    pronouns: Pronouns = _parse_pronouns(record, pedantic=pedantic)
+    tags: set[PronounTag] = _parse_tags(record, pedantic=pedantic)
+
+    if (  # specifically mark they/them as plural
+        pronouns.subject == "they"
+        and pronouns.object == "them"
+        and PronounTag.PLURAL not in tags
+    ):
+        tags.add(PronounTag.PLURAL)
+
+    return PronounRecord(pronouns=pronouns, tags=tags)
+
+
+def parse_pronoun_records(pronoun_records: list[str], *, pedantic: bool = False) -> PronounsResponse:
+    uses_any_pronouns: bool = False
+    uses_name_only: bool = False
+    records: list[PronounRecord] = []
+
+    for record in pronoun_records:
+        normalised_record: str = _normalise_record(record)
+        if len(normalised_record) == 0:          # empty record
+            continue
+        elif normalised_record.startswith("!"):  # none; use name only declarator
+            uses_name_only = True
+            continue
+        elif normalised_record.startswith("*"):  # wildcard; any pronoun is declarator
+            uses_any_pronouns = True
+            continue
+        else:                                    # pronoun set
+            parsed_record: PronounRecord = _parse_record(normalised_record, pedantic=pedantic)
+            records.append(parsed_record)
+
+    if pedantic and uses_name_only and len(records) > 0:
+        raise PODNSParserSetsAfterNone(f"{uses_name_only=} and {len(records) > 0=}.")
+
+    return PronounsResponse(
+        uses_any_pronouns=uses_any_pronouns,
+        uses_name_only=uses_name_only,
+        records=[] if uses_name_only else records,
+    )

podns/pronouns.py

@@ -0,0 +1,60 @@
+"""
+MIT License
+
+Copyright (c) 2024-present abigail phoebe <abigail@phoebe.sh>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+__all__: tuple[str, ...] = (
+    "PronounsResponse",
+    "PronounTag",
+    "Pronouns",
+)
+
+
+class PronounTag(StrEnum):
+    PREFERRED = "preferred"
+    PLURAL = "plural"
+
+
+@dataclass(slots=True, frozen=True)
+class Pronouns:
+    subject: str
+    object: str
+    possessive_determiner: str | None
+    possessive_pronoun: str | None
+    reflexive: str | None
+
+
+@dataclass(slots=True, frozen=True)
+class PronounRecord:
+    pronouns: Pronouns
+    tags: set[PronounTag]
+
+
+@dataclass(slots=True, frozen=True)
+class PronounsResponse:
+    uses_any_pronouns: bool
+    uses_name_only: bool
+    records: list[PronounRecord]

podns-0.1.1.dist-info/METADATA

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: podns
+Version: 0.1.1
+Summary: A Pronouns over DNS specification compliant Python API.
+License: MIT
+License-File: LICENSE
+Author: abigail phoebe
+Author-email: abigail@phoebe.sh
+Requires-Python: >=3.14
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: dnspython (>=2.8.0)
+Project-URL: Bug Tracker, https://github.com/ijsbol/podns_py/issues
+Project-URL: Homepage, https://github.com/ijsbol/podns_py
+Description-Content-Type: text/markdown
+
+# podns_py
+
+A [Pronouns over DNS](https://github.com/CutieZone/pronouns-over-dns/) specification compliant Python API.
+
+
+## Documentation
+
+### Fetching from domain record.
+
+If you want to fetch someones pronouns from their domain, see the below:
+
+Note that we support both synchronous and asynchronous lookups.
+
+
+```python
+import asyncio
+
+import podns.dns
+
+
+async def main() -> None:
+    domain = "abigail.sh"
+    podns.dns.fetch_pronouns_from_domain_sync(domain)
+    await podns.dns.fetch_pronouns_from_domain_async(domain)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Parsing a raw list
+
+If you already have fetched the users pronouns, or are just parsing a raw literal:
+
+```python
+import podns.parser
+
+podns.parser.parse_pronoun_records([
+    "she/her",
+    "they/them/theirs;preferred"
+])
+```
+
+### Optional pedantic `kwarg` on user APIs
+
+For all user-level APIs (that is, `podns.dns.fetch_pronouns_from_domain_*` and `podns.parser.parse_pronoun_records`), there is an optional kwarg, `pedantic`, that defaults to `False`.
+
+- Setting this to `True` will raise errors on all specification-violating parse errors from the provided records.
+- Setting this to `False` will only raise errors on egregious specification violations that make parsing impossible. When set to `False`, podns will do its' best to infer intent when met with trivial violations, it will however never return a `podns.pronouns.PronounsResponse` that violates the specification.
+

podns-0.1.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+podns/__init__.py,sha256=kMQV4rZozSEsiUq7mYsziyYgfsX3VG87jBYRqKCXL50,1485
+podns/dns.py,sha256=zGLPEvamxjRdZCFTvrEhO1Qa4QVZ5UBpaWNqNpyO264,1999
+podns/error.py,sha256=k1L5jybcQ-bdels_wsJz-1oRMrPrlyURJGcgw8ElkUs,2118
+podns/parser.py,sha256=jMypxkVDauybcAPHUma_DG6R_-mqEeUH2F82aPhSVjA,7252
+podns/pronouns.py,sha256=hcH0ZIi0SjniE3Aq53HgDu5NQF-op6Q-vaKeSyh0B68,1779
+podns/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+podns-0.1.1.dist-info/METADATA,sha256=-02_Yf6CjVSTt_F69X-DeLi2_OEdgeoacZ8gi9hAA_4,2049
+podns-0.1.1.dist-info/WHEEL,sha256=3ny-bZhpXrU6vSQ1UPG34FoxZBp3lVcvK0LkgUz6VLk,88
+podns-0.1.1.dist-info/licenses/LICENSE,sha256=wcpZDgCp7rR4gv4QLE-rmgeYYEyX3-MO9RDyGxldD0s,1099
+podns-0.1.1.dist-info/RECORD,,

podns-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.3.0
+Root-Is-Purelib: true
+Tag: py3-none-any

podns-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 abigail phoebe ୧ ‧₊˚ 🍵 ⋅ᰔᩚ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.