PyPaf 0.6.0__tar.gz → 0.7.0__tar.gz

{pypaf-0.6.0/src/PyPaf.egg-info → pypaf-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: PyPaf
-Version: 0.6.0
+Version: 0.7.0
 Summary: Formats the elements of a Royal Mail Postcode Address File entry
 Author-email: John Bard <johnbard@globalnet.co.uk>
 License: MIT
@@ -25,6 +25,8 @@ Install it from PyPI:
 
 ## Usage
 
+### Formatting
+
 May be used to format the PAF Address elements as a list of strings:
 
 ```python
@@ -98,6 +100,71 @@ address.as_dict()
 }
 ```
 
+### Premises Attributes
+
+The `sub_building_name`, `building_name` and `building_number` supplied in the source PAF Address elements need to be parsed according Programmer's Guide rules in order to correctly identify the premises elements of the address.
+
+The Address class includes a parsed premises dictionary that contains key-values that may be used to identify the premises within the thoroughfare and the sub-premises within the premises.
+
+The parsing decomposes the premises and sub-premises to its constituent parts:
+
+| Key                 | Notes |
+| ------------------- | ----------- |
+| premises_type       | If it is of a known type e.g. BLOCK, BUILDING |
+| premises_number     | Building number or leading digits of building name |
+| premises_suffix     | Non-numeric characters following leading digits of building name |
+| premises_name       | Building name, if it cannot be decomposed |
+| sub_premises_type   | If it is of a known type e.g. FLAT, UNIT |
+| sub_premises_number | Leading digits of sub-building name |
+| sub_premises_suffix | Non-numeric characters following leading digits of sub-building name |
+| sub_premises_name   | Sub-building name, if it cannot be decomposed |
+
+```python
+import paf
+self.address = paf.Address({
+    'sub_building_name': "FLAT 2B",
+    'building_name': "THE TOWER",
+    'building_number': "27",
+    'thoroughfare_name': "JOHN",
+    'thoroughfare_descriptor': "STREET",
+    'post_town': "WINCHESTER",
+    'postcode': "SO23 9AP"
+})
+address.premises()
+
+{
+    'premises_number': 27,
+    'premises_name': 'THE TOWER',
+    'sub_premises_type': 'FLAT',
+    'sub_premises_number': 2,
+    'sub_premises_suffix': 'B',
+}
+```
+
+If there are no `sub_building` or `building` elements supplied the `organisation_name` or `po_box_number` elements will be used populate the premises elements, where available.
+
+If there is no `sub_building_name` element and the `dependent_thoroughfare` elements are populated the `building` elements will be used to populate the `sub_premises` elements and the `dependent_thoroughfare` elements the `premises` elements.
+
+```python
+import paf
+self.address = paf.Address({
+    'building_name': "1A",
+    'dependent_thoroughfare_name': "SEASTONE",
+    'dependent_thoroughfare_descriptor': "COURT",
+    'thoroughfare_name': "STATION",
+    'thoroughfare_descriptor': "ROAD",
+    'post_town': "HOLT",
+    'postcode': "NR25 7HG"
+})
+address.premises()
+
+{
+    'premises_name': 'SEASTONE COURT',
+    'sub_premises_number': 1,
+    'sub_premises_suffix': 'A'
+}
+```
+
 ## Development
 
 After checking out the repo, run `pytest` to run the tests.

{pypaf-0.6.0 → pypaf-0.7.0}/README.md

@@ -10,6 +10,8 @@ Install it from PyPI:
 
 ## Usage
 
+### Formatting
+
 May be used to format the PAF Address elements as a list of strings:
 
 ```python
@@ -83,6 +85,71 @@ address.as_dict()
 }
 ```
 
+### Premises Attributes
+
+The `sub_building_name`, `building_name` and `building_number` supplied in the source PAF Address elements need to be parsed according Programmer's Guide rules in order to correctly identify the premises elements of the address.
+
+The Address class includes a parsed premises dictionary that contains key-values that may be used to identify the premises within the thoroughfare and the sub-premises within the premises.
+
+The parsing decomposes the premises and sub-premises to its constituent parts:
+
+| Key                 | Notes |
+| ------------------- | ----------- |
+| premises_type       | If it is of a known type e.g. BLOCK, BUILDING |
+| premises_number     | Building number or leading digits of building name |
+| premises_suffix     | Non-numeric characters following leading digits of building name |
+| premises_name       | Building name, if it cannot be decomposed |
+| sub_premises_type   | If it is of a known type e.g. FLAT, UNIT |
+| sub_premises_number | Leading digits of sub-building name |
+| sub_premises_suffix | Non-numeric characters following leading digits of sub-building name |
+| sub_premises_name   | Sub-building name, if it cannot be decomposed |
+
+```python
+import paf
+self.address = paf.Address({
+    'sub_building_name': "FLAT 2B",
+    'building_name': "THE TOWER",
+    'building_number': "27",
+    'thoroughfare_name': "JOHN",
+    'thoroughfare_descriptor': "STREET",
+    'post_town': "WINCHESTER",
+    'postcode': "SO23 9AP"
+})
+address.premises()
+
+{
+    'premises_number': 27,
+    'premises_name': 'THE TOWER',
+    'sub_premises_type': 'FLAT',
+    'sub_premises_number': 2,
+    'sub_premises_suffix': 'B',
+}
+```
+
+If there are no `sub_building` or `building` elements supplied the `organisation_name` or `po_box_number` elements will be used populate the premises elements, where available.
+
+If there is no `sub_building_name` element and the `dependent_thoroughfare` elements are populated the `building` elements will be used to populate the `sub_premises` elements and the `dependent_thoroughfare` elements the `premises` elements.
+
+```python
+import paf
+self.address = paf.Address({
+    'building_name': "1A",
+    'dependent_thoroughfare_name': "SEASTONE",
+    'dependent_thoroughfare_descriptor': "COURT",
+    'thoroughfare_name': "STATION",
+    'thoroughfare_descriptor': "ROAD",
+    'post_town': "HOLT",
+    'postcode': "NR25 7HG"
+})
+address.premises()
+
+{
+    'premises_name': 'SEASTONE COURT',
+    'sub_premises_number': 1,
+    'sub_premises_suffix': 'A'
+}
+```
+
 ## Development
 
 After checking out the repo, run `pytest` to run the tests.

{pypaf-0.6.0 → pypaf-0.7.0/src/PyPaf.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: PyPaf
-Version: 0.6.0
+Version: 0.7.0
 Summary: Formats the elements of a Royal Mail Postcode Address File entry
 Author-email: John Bard <johnbard@globalnet.co.uk>
 License: MIT
@@ -25,6 +25,8 @@ Install it from PyPI:
 
 ## Usage
 
+### Formatting
+
 May be used to format the PAF Address elements as a list of strings:
 
 ```python
@@ -98,6 +100,71 @@ address.as_dict()
 }
 ```
 
+### Premises Attributes
+
+The `sub_building_name`, `building_name` and `building_number` supplied in the source PAF Address elements need to be parsed according Programmer's Guide rules in order to correctly identify the premises elements of the address.
+
+The Address class includes a parsed premises dictionary that contains key-values that may be used to identify the premises within the thoroughfare and the sub-premises within the premises.
+
+The parsing decomposes the premises and sub-premises to its constituent parts:
+
+| Key                 | Notes |
+| ------------------- | ----------- |
+| premises_type       | If it is of a known type e.g. BLOCK, BUILDING |
+| premises_number     | Building number or leading digits of building name |
+| premises_suffix     | Non-numeric characters following leading digits of building name |
+| premises_name       | Building name, if it cannot be decomposed |
+| sub_premises_type   | If it is of a known type e.g. FLAT, UNIT |
+| sub_premises_number | Leading digits of sub-building name |
+| sub_premises_suffix | Non-numeric characters following leading digits of sub-building name |
+| sub_premises_name   | Sub-building name, if it cannot be decomposed |
+
+```python
+import paf
+self.address = paf.Address({
+    'sub_building_name': "FLAT 2B",
+    'building_name': "THE TOWER",
+    'building_number': "27",
+    'thoroughfare_name': "JOHN",
+    'thoroughfare_descriptor': "STREET",
+    'post_town': "WINCHESTER",
+    'postcode': "SO23 9AP"
+})
+address.premises()
+
+{
+    'premises_number': 27,
+    'premises_name': 'THE TOWER',
+    'sub_premises_type': 'FLAT',
+    'sub_premises_number': 2,
+    'sub_premises_suffix': 'B',
+}
+```
+
+If there are no `sub_building` or `building` elements supplied the `organisation_name` or `po_box_number` elements will be used populate the premises elements, where available.
+
+If there is no `sub_building_name` element and the `dependent_thoroughfare` elements are populated the `building` elements will be used to populate the `sub_premises` elements and the `dependent_thoroughfare` elements the `premises` elements.
+
+```python
+import paf
+self.address = paf.Address({
+    'building_name': "1A",
+    'dependent_thoroughfare_name': "SEASTONE",
+    'dependent_thoroughfare_descriptor': "COURT",
+    'thoroughfare_name': "STATION",
+    'thoroughfare_descriptor': "ROAD",
+    'post_town': "HOLT",
+    'postcode': "NR25 7HG"
+})
+address.premises()
+
+{
+    'premises_name': 'SEASTONE COURT',
+    'sub_premises_number': 1,
+    'sub_premises_suffix': 'A'
+}
+```
+
 ## Development
 
 After checking out the repo, run `pytest` to run the tests.

{pypaf-0.6.0 → pypaf-0.7.0}/src/PyPaf.egg-info/SOURCES.txt

@@ -9,12 +9,19 @@ src/paf/__init__.py
 src/paf/address.py
 src/paf/attribute.py
 src/paf/immutable.py
+src/paf/initiator.py
 src/paf/lineable.py
-src/paf/premises_extender.py
 src/paf/thoroughfare_locality.py
 src/paf/version.py
 src/paf/premises/__init__.py
-src/paf/premises/common.py
+src/paf/premises/attribute.py
+src/paf/premises/building_type.py
+src/paf/premises/dependent_premisable.py
+src/paf/premises/exception.py
+src/paf/premises/extender.py
+src/paf/premises/lineable.py
+src/paf/premises/premisable.py
+src/paf/premises/premises.py
 src/paf/premises/rule000.py
 src/paf/premises/rule001.py
 src/paf/premises/rule010.py
@@ -22,6 +29,7 @@ src/paf/premises/rule011.py
 src/paf/premises/rule101.py
 src/paf/premises/rule110.py
 src/paf/premises/rule111.py
+src/paf/premises/split.py
 tests/test_empty.py
 tests/test_exception_i.py
 tests/test_exception_ii.py
@@ -30,6 +38,7 @@ tests/test_exception_iv.py
 tests/test_immutability.py
 tests/test_mainfile.py
 tests/test_po_box.py
+tests/test_premises.py
 tests/test_rule_1.py
 tests/test_rule_2.py
 tests/test_rule_3.py

{pypaf-0.6.0 → pypaf-0.7.0}/src/paf/address.py

@@ -1,24 +1,24 @@
 """PAF Address"""
 
 # Tried using dataclasses.dataclass(frozen=True) decorator for immutablity but did not work"""
+from .initiator import attribute_init
+from .attribute import AttributeMixin
 from .immutable import ImmutableMixin
 from .lineable import LineableMixin
+from .thoroughfare_locality import ThoroughfareLocalityMixin
+from .premises.premises import Premises
 
-class Address(ImmutableMixin, LineableMixin):
+class Address(ImmutableMixin, AttributeMixin, ThoroughfareLocalityMixin, LineableMixin):
     """Main PAF Address class"""
 
-    def __init__(self, args):
+    @attribute_init
+    def __init__(self, *args):
         """Initialise Address elements"""
-        for key in self.__class__.attrs: # pylint: disable=not-an-iterable
-            object.__setattr__(self, key, '')
-        for key, val in args.items():
-            if hasattr(self, key):
-                object.__setattr__(self, key, val)
-        self.extend_premises()
+        object.__setattr__(self, 'premises', Premises(*args))
 
     def __repr__(self):
         """Return full representation of an Address"""
-        args = {k: getattr(self, k) for k in self.__class__.attrs if getattr(self, k, None)} # pylint: disable=not-an-iterable
+        args = {k: getattr(self, k) for k in list(self.attrs) if getattr(self, k, None)}
         return self.__class__.__name__ + '(' + str(args) + ')'
 
     def __str__(self):
@@ -30,9 +30,9 @@ class Address(ImmutableMixin, LineableMixin):
 
     def __iter__(self):
         """Return Address as iterable"""
-        yield from self.lines.__iter__()
+        yield from list(self.lines)
         if not self.is_empty('postcode'):
-            yield from [getattr(self, 'postcode')].__iter__()
+            yield from list([getattr(self, 'postcode')])
 
     def as_str(self):
         """Return Address as string"""

pypaf-0.7.0/src/paf/attribute.py

@@ -0,0 +1,43 @@
+"""Attribute Mixin"""
+
+class AttributeMixin():
+    """Address elements and derived properties"""
+
+    @classmethod
+    @property
+    def premises_attrs(cls):
+        """Returns Paf premises elements"""
+        return (
+            'organisation_name', 'department_name',
+                'sub_building_name', 'building_name', 'building_number',
+                'po_box_number'
+            )
+
+    @classmethod
+    @property
+    def post_attrs(cls):
+        """Returns Paf post elements"""
+        return ('post_town', 'postcode')
+
+    @classmethod
+    @property
+    def other_attrs(cls):
+        """Returns Paf other elements"""
+        return ('concatenation_indicator', 'udprn')
+
+    @classmethod
+    @property
+    def attrs(cls):
+        """Returns all Paf address elements"""
+        return(
+            cls.premises_attrs
+                + cls.dependent_thoroughfare_attrs
+                + cls.thoroughfare_attrs
+                + cls.locality_attrs
+                + cls.post_attrs
+                + cls.other_attrs
+            )
+
+    def is_empty(self, attr):
+        """Returns if attribute value is empty"""
+        return getattr(self, attr, '') == ''

pypaf-0.7.0/src/paf/initiator.py

@@ -0,0 +1,18 @@
+"""Initiator Decorator"""
+
+import functools
+
+def attribute_init(func):
+    """Decorator to initiate an object based on a list of attributes"""
+
+    @functools.wraps(func)
+    def wrapper(self, *args, **kwargs):
+        """Initiate properties from specified dict"""
+        for key in list(getattr(self, 'attrs', [])):
+            object.__setattr__(self, key, '')
+        for key, val in args[0].items():
+            if hasattr(self, key):
+                object.__setattr__(self, key, str(val))
+        return func(self, *args, **kwargs)
+
+    return wrapper

pypaf-0.7.0/src/paf/lineable.py

@@ -0,0 +1,33 @@
+"""Lineable Mixin"""
+
+from itertools import chain
+
+class LineableMixin():
+    """Converts Paf address elements into list of address lines"""
+
+    @classmethod
+    @property
+    def optional_lines_attrs(cls):
+        """Returns optional address line attributes"""
+        return ('thoroughfares_and_localities',)
+
+    @classmethod
+    @property
+    def lines_attrs(cls):
+        """Returns optional address line attributes and post_town"""
+        return cls.optional_lines_attrs + ('post_town',)
+
+    @property
+    def optional_lines(self):
+        """Returns address lines, excluding post_town and postcode"""
+        return self.premises.lines + self._lines(self.optional_lines_attrs)
+
+    @property
+    def lines(self):
+        """Returns address lines, excluding postcode"""
+        return self.premises.lines + self._lines(self.lines_attrs)
+
+    def _lines(self, attrs):
+        """Returns list of address lines from specified attributes"""
+        lines = list(filter(None, [getattr(self, k, None) for k in attrs]))
+        return list(chain(*[line if isinstance(line, list) else [line] for line in lines]))

pypaf-0.7.0/src/paf/premises/attribute.py

@@ -0,0 +1,39 @@
+"""Attribute Mixin"""
+
+class AttributeMixin():
+    """Premises elements and derived properties"""
+
+    @classmethod
+    @property
+    def organisation_attrs(cls):
+        """Returns Paf organisation elements"""
+        return ('organisation_name', 'department_name')
+
+    @classmethod
+    @property
+    def building_attrs(cls):
+        """Returns Paf building elements"""
+        return ('sub_building_name', 'building_name', 'building_number')
+
+    @classmethod
+    @property
+    def other_attrs(cls):
+        """Returns Paf other elements"""
+        return ('po_box_number', 'concatenation_indicator')
+
+    @classmethod
+    @property
+    def attrs(cls):
+        """Returns all Paf premises elements"""
+        return(
+            cls.organisation_attrs
+                + cls.building_attrs
+                + cls.dependent_thoroughfare_attrs
+                + cls.thoroughfare_attrs
+                + cls.locality_attrs
+                + cls.other_attrs
+            )
+
+    def is_empty(self, attr):
+        """Returns if attribute value is empty"""
+        return getattr(self, attr, '') == ''

pypaf-0.7.0/src/paf/premises/building_type.py

@@ -0,0 +1,29 @@
+"""Building Types"""
+
+from .split import SplitMixin
+
+class BuildingTypeMixin(SplitMixin):
+    """Determines if a string represents a known building type"""
+
+    @classmethod
+    @property
+    def known_building_types(cls):
+        """Returns known building types"""
+        return (
+            "BACK OF", "BLOCK", "BLOCKS", "BUILDING", "MAISONETTE", "MAISONETTES", "REAR OF",
+            "SHOP", "SHOPS", "STALL", "STALLS", "SUITE", "SUITES", "UNIT", "UNITS", "PO BOX"
+            )
+
+    @classmethod
+    @property
+    def known_sub_building_types(cls):
+        """Returns known sub-building types"""
+        return cls.known_building_types + ("FLAT", "FLATS")
+
+    def is_known_building_type(self, attr='building_name'):
+        """Returns if attribute starts with a known type"""
+        return self.but_last_word(attr) in self.known_building_types
+
+    def is_known_sub_building_type(self, attr='sub_building_name'):
+        """Returns if attribute starts with a known type"""
+        return self.but_last_word(attr) in self.known_sub_building_types

pypaf-0.7.0/src/paf/premises/dependent_premisable.py

@@ -0,0 +1,34 @@
+"""Dependent Premisable Mixin"""
+
+from .premisable import PremisableMixin
+
+class DependentPremisableMixin(PremisableMixin):
+    """Returns the values for the premises properties"""
+
+    @property
+    def _premises_number(self):
+        """Returns premises number"""
+        if getattr(self, 'dependent_thoroughfare', '') != '':
+            return ''
+        return super()._premises_number
+
+    @property
+    def _premises_name(self):
+        """Returns premises name"""
+        if getattr(self, 'dependent_thoroughfare', '') != '':
+            return getattr(self, 'dependent_thoroughfare', '')
+        return super()._premises_name
+
+    @property
+    def _sub_premises_number(self):
+        """Returns sub-premises number"""
+        if getattr(self, 'dependent_thoroughfare', '') != '':
+            return super()._premises_number
+        return super()._sub_premises_number
+
+    @property
+    def _sub_premises_name(self):
+        """Returns sub-premises name"""
+        if getattr(self, 'dependent_thoroughfare', '') != '':
+            return super()._premises_name
+        return super()._sub_premises_name

pypaf-0.7.0/src/paf/premises/exception.py

@@ -0,0 +1,51 @@
+"""Exceptions"""
+
+import re
+from .building_type import BuildingTypeMixin
+from .split import SplitMixin
+
+class ExceptionMixin(BuildingTypeMixin, SplitMixin):
+    """Exceptions"""
+
+    @classmethod
+    def __is_exception_i(cls, val):
+        """Returns if first and last characters are numeric"""
+        return re.fullmatch(r'^[\d](?:.*[\d])?$', val)
+
+    @classmethod
+    def __is_exception_ii(cls, val):
+        """Returns if first and penultimate characters are numeric, and last is alphabetic"""
+        return re.fullmatch(r'^([\d][a-zA-Z]|[\d].*?[\d][a-zA-Z])$', val)
+
+    @classmethod
+    def __is_exception_iii(cls, val):
+        """Returns if single non-whitespace character"""
+        return re.fullmatch(r'^[^ \t\r\n\v\f]$', val)
+
+    @classmethod
+    def __is_exception(cls, val):
+        """Returns if value is an exception"""
+        return (
+            cls.__is_exception_i(val)
+                or cls.__is_exception_ii(val)
+                or cls.__is_exception_iii(val)
+            )
+
+    def __is_exception_iv(self, attr):  # pylint: disable=unused-argument
+        """Returns if value starts with a known building type
+           and ends with numeric range or numeric alpha suffix"""
+        # Do not include suffix check as does not account for values such as BLOCK B
+        return self.is_known_building_type(attr)
+        # and re.match(r'^\d', splitstring.last_word(getattr(self, attr, None)))
+
+    def is_exception(self, attr):
+        """Returns if attribute is an exception"""
+        return self.__is_exception(getattr(self, attr, None))
+
+    def is_split_exception(self, attr):
+        """Returns if attribute should be split"""
+        return (
+            self.__is_exception(self.last_word(attr))
+                and not self.last_word(attr).isdigit()
+                and not self.__is_exception_iv(attr)
+            )

pypaf-0.7.0/src/paf/premises/extender.py

@@ -0,0 +1,24 @@
+"""Premises Extender Mixin"""
+
+import sys
+from .rule000 import Rule000 # pylint: disable=unused-import
+from .rule001 import Rule001 # pylint: disable=unused-import
+from .rule010 import Rule010 # pylint: disable=unused-import
+from .rule011 import Rule011 # pylint: disable=unused-import
+from .rule101 import Rule101 # pylint: disable=unused-import
+from .rule110 import Rule110 # pylint: disable=unused-import
+from .rule111 import Rule111 # pylint: disable=unused-import
+
+class ExtenderMixin():
+    """Dynamic Premises processing"""
+
+    @property
+    def rule(self):
+        """Returns premises rule class"""
+        rule = ''.join(['0' if self.is_empty(k) else '1' for k in self.building_attrs])
+        return getattr(sys.modules[__name__], 'Rule' + rule)
+
+    def extend(self):
+        """Dynamically extends instance with appropriate rule"""
+        base_cls = self.__class__
+        object.__setattr__(self, '__class__', type(base_cls.__name__, (base_cls, self.rule), {}))

pypaf-0.7.0/src/paf/premises/lineable.py

@@ -0,0 +1,26 @@
+"""Lineable Mixin"""
+
+from itertools import chain
+
+class LineableMixin():
+    """Converts Paf address premises elements into list of lines"""
+
+    @property
+    def lines_attrs(self):
+        """Returns premises line attributes"""
+        return self.organisation_attrs + ('po_box',) + self.rule_attrs
+
+    @property
+    def lines(self):
+        """Returns premises lines"""
+        return self._lines(self.lines_attrs)
+
+    @property
+    def po_box(self):
+        """Returns PO Box"""
+        return '' if self.is_empty('po_box_number') else f"PO BOX {getattr(self, 'po_box_number')}"
+
+    def _lines(self, attrs):
+        """Returns list of premises lines from specified attributes"""
+        lines = list(filter(None, [getattr(self, k, None) for k in attrs]))
+        return list(chain(*[line if isinstance(line, list) else [line] for line in lines]))