PyPaf 0.1.0__py3-none-any.whl

PyPaf-0.1.0.dist-info/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 John Bard
+
+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.

PyPaf-0.1.0.dist-info/METADATA

@@ -0,0 +1,72 @@
+Metadata-Version: 2.2
+Name: PyPaf
+Version: 0.1.0
+Summary: Formats the elements of a Royal Mail Postcode Address File entry
+Author-email: John Bard <johnbard@globalnet.co.uk>
+License: MIT
+Project-URL: Homepage, https://github.com/drabjay/pypaf
+Project-URL: Repository, https://github.com/drabjay/pypaf.git
+Project-URL: Issues, https://github.com/drabjay/paf/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+
+# PyPaf
+
+Formats the elements of a Royal Mail Postcode Address File entry according to the rules described in the [Royal Mail Programmer's Guide Edition 7, Version 5.0](http://www.royalmail.com/sites/default/files/docs/pdf/programmers_guide_edition_7_v5.pdf)
+
+## Installation
+
+Install it from PyPI:
+
+    $ pip install pypaf
+
+## Usage
+
+May be used to format the PAF elements as an array of strings:
+
+```python
+from paf import Paf
+paf = Paf({
+    'building_name': "1-2",
+    'thoroughfare_name': "NURSERY",
+    'thoroughfare_descriptor': "LANE",
+    'dependent_locality': "PENN",
+    'post_town': "HIGH WYCOMBE",
+    'postcode': "HP10 8LS"
+})
+paf.list()
+
+['1-2 NURSERY LANE', 'PENN', 'HIGH WYCOMBE', 'HP10 8LS']
+```
+
+Or as a single string:
+
+```python
+from paf import Paf
+paf = Paf({
+    'building_name': "1-2",
+    'thoroughfare_name': "NURSERY",
+    'thoroughfare_descriptor': "LANE",
+    'dependent_locality': "PENN",
+    'post_town': "HIGH WYCOMBE",
+    'postcode': "HP10 8LS"
+})
+str(paf)
+
+'1-2 NURSERY LANE, PENN, HIGH WYCOMBE. HP10 8LS'
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/drabjay/pypaf. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The package is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the PyPaf project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/drabjayc/pypaf/blob/master/CODE_OF_CONDUCT.md).

PyPaf-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+paf/__init__.py,sha256=w2HsvPirX6Zw95ZHBiYjUpHDHvwmN-O6zggCvhGuRLE,109
+paf/attribute.py,sha256=MDMBDxuTvniQt0UWgMB2dslg4hajVYjm8pMHW2In8tk,1890
+paf/lineable.py,sha256=L-6zi9h6IrUDw2hwRUPRa65MRe82pXcOxu4essEKoyE,948
+paf/paf.py,sha256=eQoFBj1hJDZKpOJzNPhRYdHiN91iIqkjhCeRBHD6Ko4,1035
+paf/premises_extender.py,sha256=CusZwvXYAC8GH0_NgDEf9fkpcxVkrpNW5wEcw_A-g8E,1124
+paf/thoroughfare_locality.py,sha256=0A8xJ7JrVHHXMh2yr8oBqX8Ec2Br10ZrK7ujawQ_1yQ,1866
+paf/version.py,sha256=I7CCHRp7v4pFRh5W5cdIJIuET_tRwULAKmJT230wB3E,37
+paf/premises/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+paf/premises/common.py,sha256=0BLCMLwZU1yJTuXeHhQKzYpnxQOcJDp2m_CUvsiKXBE,1358
+paf/premises/rule000.py,sha256=kzzHNJ2wxgXuJSqu4VyNizBre2aCtWpqFnAuUMOX5Nc,375
+paf/premises/rule001.py,sha256=B6QOIkbeAMwae3xHrjqaMPiPi8zitpxKM5m1K3FP8TI,411
+paf/premises/rule010.py,sha256=AtvnwcW6O_xb72awazHcQXVduMTcnRCbE_P3LvP1zjM,1656
+paf/premises/rule011.py,sha256=2rF4COJkuycD9uhbkcokMotFAWtBrWfCLBE3-aT5xwY,428
+paf/premises/rule101.py,sha256=4Ml3BQz2LKyT4Of809el6exVBjFz5Ox1VlnRS1ivc0Q,1075
+paf/premises/rule110.py,sha256=dZjhPJlV3z3DbFxBuxRRm8SwxlnRuvIEbiKPRuwxLgg,704
+paf/premises/rule111.py,sha256=_A4zdMc8B4uqtb-JlvhpUZebckmYRtyZGCwzACTztiA,579
+PyPaf-0.1.0.dist-info/LICENSE.txt,sha256=mS-ROSs81MzkitAWqX9Mw16kRQ1mZTWsmJusmZqhUvA,1075
+PyPaf-0.1.0.dist-info/METADATA,sha256=KzcjptRQ6YwnKOexbukSbXTEuZ7mDZ3Tb6xw_7Un-lY,2255
+PyPaf-0.1.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+PyPaf-0.1.0.dist-info/top_level.txt,sha256=XUoA1HTds1ccl3RQvWR2pX4dcMMKnqryRf1PMZBPz6I,4
+PyPaf-0.1.0.dist-info/RECORD,,

PyPaf-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.8.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

PyPaf-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+paf

paf/__init__.py

@@ -0,0 +1,6 @@
+"""__init__ file"""
+
+from .paf import Paf
+from .version import __version__
+
+__all__ = ["Paf", "__version__"]

paf/attribute.py

@@ -0,0 +1,66 @@
+"""Attribute Mixin"""
+
+class AttributeMixin():
+    """Base Paf address elements and derived properties"""
+
+    @classmethod
+    @property
+    def organisation_attrs(cls):
+        """Returns Paf organisation elements"""
+        return ['organisation_name', 'department_name']
+
+    @classmethod
+    @property
+    def premises_attrs(cls):
+        """Returns Paf premises elements"""
+        return ['sub_building_name', 'building_name', 'building_number']
+
+    @classmethod
+    @property
+    def dependent_thoroughfare_attrs(cls):
+        """Returns Paf dependent thoroughfare elements"""
+        return ['dependent_thoroughfare_name', 'dependent_thoroughfare_descriptor']
+
+    @classmethod
+    @property
+    def thoroughfare_attrs(cls):
+        """Returns Paf thoroughfare elements"""
+        return ['thoroughfare_name', 'thoroughfare_descriptor']
+
+    @classmethod
+    @property
+    def locality_attrs(cls):
+        """Returns Paf localoty elements"""
+        return ['double_dependent_locality', 'dependent_locality']
+
+    @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 ['po_box_number', 'udprn', 'concatenation_indicator']
+
+    @classmethod
+    @property
+    def attrs(cls):
+        """Returns all Paf address elements"""
+        return(
+            cls.organisation_attrs +
+                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"""
+        if getattr(self, attr, '') == '':
+            return True
+        return False

paf/lineable.py

@@ -0,0 +1,27 @@
+"""Lineable Mixin"""
+
+from itertools import chain
+from .thoroughfare_locality import ThoroughfareLocalityMixin
+
+class LineableMixin(ThoroughfareLocalityMixin):
+    """Converts Paf address elements into list of address lines, excluding postcode"""
+
+    @classmethod
+    @property
+    def lines_attrs(cls):
+        """Returns Paf address line attributes"""
+        return(
+            cls.organisation_attrs +
+                ['po_box', 'premises', 'thoroughfares_and_localities', 'post_town']
+            )
+
+    @property
+    def lines(self):
+        """Returns Paf as list of address lines"""
+        lines = list(filter(None, [getattr(self, k, None) for k in self.__class__.lines_attrs]))
+        return list(chain(*[line if isinstance(line, list) else [line] for line in lines]))
+
+    @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')}"

paf/paf.py

@@ -0,0 +1,33 @@
+"""Paf"""
+
+from .lineable import LineableMixin
+
+class Paf(LineableMixin):
+    """Main Paf class"""
+
+    def __init__(self, args):
+        """Initialise Paf address elements"""
+        for key in self.__class__.attrs:
+            setattr(self, key, '')
+        for key, val in args.items():
+            if hasattr(self, key):
+                setattr(self, key, val)
+        self.extend_premises()
+
+    def __repr__(self):
+        """Return full representation of Paf"""
+        args = {k: getattr(self, k) for k in self.__class__.attrs if getattr(self, k, None)}
+        return self.__class__.__name__ + '(' + str(args) + ')'
+
+    def __str__(self):
+        """Return Paf as string"""
+        line = ', '.join(self.lines)
+        if self.is_empty('postcode'):
+            return line
+        return '. '.join([line] + [getattr(self, 'postcode')])
+
+    def list(self):
+        """Return Paf as list of strings"""
+        if self.is_empty('postcode'):
+            return self.lines
+        return self.lines + [getattr(self, 'postcode')]

paf/premises/common.py

@@ -0,0 +1,38 @@
+"""Common"""
+
+import re
+
+class Common:
+    """Common premises processing"""
+
+    @property
+    def premises_rule_attrs(self):
+        """Abstract method to be implemented by the Rule"""
+
+    @property
+    def premises(self):
+        """Returns premises list"""
+        return [getattr(self, k) for k in self.premises_rule_attrs]
+
+    @property
+    def name_and_thoroughfare_or_locality(self):
+        """Returns building number and first thoroughfare or locality"""
+        return self._concatenate(['building_name', 'first_thoroughfare_or_locality'])
+
+    @property
+    def number_and_thoroughfare_or_locality(self):
+        """Returns building number and first thoroughfare or locality"""
+        return self._concatenate(['building_number', 'first_thoroughfare_or_locality'])
+
+    @property
+    def sub_name_and_name(self):
+        """Returns sub-building name and building name"""
+        return self._concatenate(['sub_building_name', 'building_name'])
+
+    def is_exception(self, attr):
+        """Returns if value is an exception"""
+        return re.match(r'^(.|[\d][a-zA-Z]|[\d].*?[\d][a-zA-Z]?)$', getattr(self, attr, None))
+
+    def _concatenate(self, keys, concatenator=' '):
+        """Returns specified attributes concatenated with a specified separator"""
+        return concatenator.join(filter(None, [getattr(self, k, None) for k in keys]))

paf/premises/rule000.py

@@ -0,0 +1,16 @@
+"""Rule 1"""
+
+from .common import Common
+
+class Rule000(Common):
+    """Rule 1 processing"""
+
+    @property
+    def premises_rule_attrs(self):
+        """Returns premises list"""
+        return []
+
+    @property
+    def does_premises_include_first_thoroughfare_or_locality(self):
+        """Returns if premises includes first thoroughfare or locality"""
+        return False

paf/premises/rule001.py

@@ -0,0 +1,16 @@
+"""Rule 2"""
+
+from .common import Common
+
+class Rule001(Common):
+    """Rule 2 processing"""
+
+    @property
+    def premises_rule_attrs(self):
+        """Returns premises list"""
+        return ['number_and_thoroughfare_or_locality']
+
+    @property
+    def does_premises_include_first_thoroughfare_or_locality(self):
+        """Returns if premises includes first thoroughfare or locality"""
+        return True

paf/premises/rule010.py

@@ -0,0 +1,46 @@
+"""Rule 3"""
+
+import re
+from .common import Common
+
+class Rule010(Common):
+    """Rule 3 processing"""
+
+    @property
+    def premises_rule_attrs(self):
+        """Returns premises list"""
+        if self.is_exception('building_name'):
+            return ['name_and_thoroughfare_or_locality']
+        if self.is_building_name_split_exception:
+            return ['building_name_but_last_word', 'name_last_word_and_thoroughfare_or_locality']
+        return ['building_name']
+
+    @property
+    def does_premises_include_first_thoroughfare_or_locality(self):
+        """Returns if premises includes first thoroughfare or locality"""
+        return self.is_exception('building_name') or self.is_building_name_split_exception
+
+    @property
+    def is_building_name_split_exception(self):
+        """Returns if building name should be split"""
+        return(
+            self.is_exception('building_name_last_word') and
+                not re.match(r'^\d+$', self.building_name_last_word)
+            )
+
+    @property
+    def building_name_last_word(self):
+        """Returns last word of the building name"""
+        *_, last = getattr(self, 'building_name', '').split()
+        return last
+
+    @property
+    def building_name_but_last_word(self):
+        """Returns all but last word of the building name"""
+        *first, _ = getattr(self, 'building_name', '').split()
+        return ' '.join(first)
+
+    @property
+    def name_last_word_and_thoroughfare_or_locality(self):
+        """Returns last word of building name and first thoroughfare or locality"""
+        return self._concatenate(['building_name_last_word', 'first_thoroughfare_or_locality'])

paf/premises/rule011.py

@@ -0,0 +1,16 @@
+"""Rule 4"""
+
+from .common import Common
+
+class Rule011(Common):
+    """Rule 4 processing"""
+
+    @property
+    def premises_rule_attrs(self):
+        """Returns premises list"""
+        return ['building_name', 'number_and_thoroughfare_or_locality']
+
+    @property
+    def does_premises_include_first_thoroughfare_or_locality(self):
+        """Returns if premises includes first thoroughfare or locality"""
+        return True

paf/premises/rule101.py

@@ -0,0 +1,30 @@
+"""Rule 5"""
+
+from .common import Common
+
+class Rule101(Common):
+    """Rule 5 processing"""
+
+    @property
+    def premises_rule_attrs(self):
+        """Returns premises list"""
+        if getattr(self, 'concatenation_indicator', '') == 'Y':
+            return ['number_sub_name_and_thoroughfare_or_locality']
+        return ['sub_building_name', 'number_and_thoroughfare_or_locality']
+
+    @property
+    def does_premises_include_first_thoroughfare_or_locality(self):
+        """Returns if premises includes first thoroughfare or locality"""
+        return True
+
+    @property
+    def building_number_and_sub_building_name(self):
+        """Returns building number and sub-building name"""
+        return self._concatenate(['building_number', 'sub_building_name'], '')
+
+    @property
+    def number_sub_name_and_thoroughfare_or_locality(self):
+        """Returns building number, sub-building name and first thoroughfare or locality"""
+        return(self._concatenate([
+            'building_number_and_sub_building_name', 'first_thoroughfare_or_locality'
+            ]))

paf/premises/rule110.py

@@ -0,0 +1,20 @@
+"""Rule 6"""
+
+from .common import Common
+
+class Rule110(Common):
+    """Rule 6 processing"""
+
+    @property
+    def premises_rule_attrs(self):
+        """Returns premises list"""
+        if self.is_exception('sub_building_name'):
+            return['sub_name_and_name']
+        if self.is_exception('building_name'):
+            return['sub_building_name', 'name_and_thoroughfare_or_locality']
+        return ['sub_building_name', 'building_name']
+
+    @property
+    def does_premises_include_first_thoroughfare_or_locality(self):
+        """Returns if premises includes first thoroughfare or locality"""
+        return (not self.is_exception('sub_building_name')) and self.is_exception('building_name')

paf/premises/rule111.py

@@ -0,0 +1,18 @@
+"""Rule 7"""
+
+from .common import Common
+
+class Rule111(Common):
+    """Rule 7 processing"""
+
+    @property
+    def premises_rule_attrs(self):
+        """Returns premises list"""
+        if self.is_exception('sub_building_name'):
+            return['sub_name_and_name', 'number_and_thoroughfare_or_locality']
+        return ['sub_building_name', 'building_name', 'number_and_thoroughfare_or_locality']
+
+    @property
+    def does_premises_include_first_thoroughfare_or_locality(self):
+        """Returns if premises includes first thoroughfare or locality"""
+        return True

paf/premises_extender.py

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

paf/thoroughfare_locality.py

@@ -0,0 +1,51 @@
+"""Thoroughfare and Locality Mixin"""
+
+from .premises_extender import PremisesExtenderMixin
+
+class ThoroughfareLocalityMixin(PremisesExtenderMixin):
+    """Thoroughfare and locality processing"""
+
+    @classmethod
+    @property
+    def thoroughfare_and_locality_attrs(cls):
+        """Returns Paf address line attributes"""
+        return ['dependent_thoroughfare', 'thoroughfare'] + cls.locality_attrs
+
+    @property
+    def thoroughfares_and_localities(self):
+        """Returns thoroughfares and localities list"""
+        attrs = self.__class__.thoroughfare_and_locality_attrs
+        return [getattr(self, k) for k in attrs if not self.is_used_or_empty(k)]
+
+    @property
+    def dependent_thoroughfare(self):
+        """Returns dependent thoroughfare"""
+        return self._concatenate(self.__class__.dependent_thoroughfare_attrs)
+
+    @property
+    def thoroughfare(self):
+        """Returns thoroughfare"""
+        return self._concatenate(self.__class__.thoroughfare_attrs)
+
+    @property
+    def first_thoroughfare_or_locality_attr(self):
+        """Returns name of first populated thoroughfare or locality attribute"""
+        for k in self.__class__.thoroughfare_and_locality_attrs:
+            if not self.is_empty(k):
+                return k
+        return None
+
+    @property
+    def first_thoroughfare_or_locality(self):
+        """Returns first populated thoroughfare or locality value"""
+        attr = self.first_thoroughfare_or_locality_attr
+        return getattr(self, attr) if attr is not None else ''
+
+    def is_used_or_empty(self, attr):
+        """Returns if attribute value is empty or has already been used"""
+        if self.is_empty(attr):
+            return True
+        return(
+            attr == self.first_thoroughfare_or_locality_attr and
+                self.does_premises_include_first_thoroughfare_or_locality
+            )

paf/version.py

@@ -0,0 +1,3 @@
+"""Version"""
+
+__version__ = '0.1.0'