chg: Improve doc

.github/workflows/mypy.yml

@@ -17,7 +17,7 @@ jobs:
     steps:
     - uses: actions/checkout@v3
     - name: Set up Python ${{matrix.python-version}}
-      uses: actions/setup-python@v3
+      uses: actions/setup-python@v4
       with:
         python-version: ${{matrix.python-version}}
 

.github/workflows/python-package.yml

@@ -21,7 +21,7 @@ jobs:
     steps:
     - uses: actions/checkout@v3
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v3
+      uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
 

pypdns/api.py

@@ -1,4 +1,4 @@
-#!/bin/python
+#!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 
 import json
@@ -8,7 +8,6 @@
 from functools import cached_property
 from importlib.metadata import version
 from typing import Optional, Tuple, List, Dict, Union, Any, TypedDict, overload, Literal, Generator
-# from urllib.parse import urljoin, urlparse
 
 import requests
 from requests import Session, Response
@@ -50,9 +49,12 @@ class TypedPDNSRecord(TypedDict, total=False):
 
 
 class PDNSRecord:
+    '''A pythonesque Passive DNS record,
+       see RFC for details: https://www.ietf.org/id/draft-dulaunoy-dnsop-passive-dns-cof-10.html
+    '''
+    __slots__ = ('_record', )
 
     def __init__(self, record: Dict[str, Optional[Union[str, int, bool, List[str], Dict[Any, Any]]]]):
-        '''A pythonesque Passive DNS record'''
         self._record = record
 
     @property
@@ -148,65 +150,98 @@ def record(self) -> TypedPDNSRecord:
 
     @property
     def rrname(self) -> str:
+        '''The name of the queried resource'''
         return self.record['rrname']
 
     @property
     def rrtype(self) -> str:
+        '''The resource record type as seen by the passive DNS'''
         return self.record['rrtype']
 
     @property
     def rdata(self) -> Union[str, List[str]]:
+        '''The resource records of the queried resource'''
         return self.record['rdata']
 
     @property
     def time_first(self) -> int:
+        '''The first time that the record / unique tuple (rrname, rrtype, rdata)
+           has been seen by the passive DNS
+        '''
         return self.record['time_first']
 
     @property
     def time_last(self) -> int:
+        '''The last time that the record / unique tuple (rrname, rrtype, rdata)
+           has been seen by the passive DNS
+        '''
         return self.record['time_last']
 
     def __repr__(self) -> str:
         return f'PDNSRecord(rrname="{self.rrname}", rrtype="{self.rrtype}", rdata="{self.rdata}", time_first={self.time_first}, time_last={self.time_last})'
 
-    @property
+    @cached_property
     def time_first_datetime(self) -> datetime:
+        '''The first time that the record / unique tuple (rrname, rrtype, rdata)
+           has been seen by the passive DNS, as a python datetime.
+        '''
         return datetime.fromtimestamp(self.time_first)
 
-    @property
+    @cached_property
     def time_last_datetime(self) -> datetime:
+        '''The last time that the record / unique tuple (rrname, rrtype, rdata)
+           has been seen by the passive DNS, as a python datetime.
+        '''
         return datetime.fromtimestamp(self.time_last)
 
     @property
     def count(self) -> Optional[int]:
+        '''How many authoritative DNS answers were received at the Passive DNS Server's
+           collectors with exactly the given set of values as answers
+        '''
         return self.record.get('count')
 
     @property
     def bailiwick(self) -> Optional[str]:
+        '''The best estimate of the apex of the zone where this data is authoritative'''
         return self.record.get('bailiwick')
 
     @property
     def sensor_id(self) -> Optional[str]:
+        '''The sensor information where the record was seen.'''
         return self.record.get('sensor_id')
 
     @property
     def zone_time_first(self) -> Optional[int]:
+        '''The first time that the unique tuple (rrname, rrtype, rdata) record
+           has been seen via master file import
+        '''
         return self.record.get('zone_time_first')
 
     @property
     def zone_time_last(self) -> Optional[int]:
+        '''The last time that the unique tuple (rrname, rrtype, rdata) record
+           has been seen via master file import
+        '''
         return self.record.get('zone_time_last')
 
     @property
     def origin(self) -> Optional[str]:
+        '''The resource origin of the Passive DNS response'''
         return self.record.get('origin')
 
     @property
     def time_first_ms(self) -> Optional[int]:
+        '''The first time that the record / unique tuple (rrname, rrtype, rdata)
+           has been seen by the passive DNS, in miliseconds since 1st of January 1970 (UTC).
+        '''
         return self.record.get('time_first_ms')
 
     @property
     def time_last_ms(self) -> Optional[int]:
+        '''The first time that the record / unique tuple (rrname, rrtype, rdata)
+           has been seen by the passive DNS, in miliseconds since 1st of January 1970 (UTC).
+        '''
         return self.record.get('time_last_ms')
 
     @property
@@ -280,7 +315,7 @@ def iter_query(self, q: str,
         Note: the order is non-deterministic.
 
         :param q: The query
-        :param filter_rrtype: The filter, must be a valid RR Type or the response will be enpty.
+        :param filter_rrtype: The filter, must be a valid RR Type or the response will be empty.
         :param break_on_errors: If there is an error, stop iterating and break immediately
         '''
         cursor = -1