Package: iwp3tb
Ish West Python 3 ToolboxA collection of random handy tools.Table of ContentsModule iwp3tb.ancestorsExampleClass AncestorsParametersModule iwp3tb.multitonConceptExamplesBasic MultitonCustom MultitonSingletonFunction implementationFunction implementation_namedFunction multitonFunction singletonClass MultitonErrorAncestorsDescendantsClass NoRegistrarParentAncestorsClass AlreadyHasRegistrarParentAncestorsClass RegistrarAlreadyHasAttributeAncestorsToolsDocs generatorPdoc Virtual EnvironmentPdoc TemplatesUnit TestsModule iwp3tb.ancestorsA handy iterator through a class' custom ancestors.Examplefromiwp3tbimportAncestorsfromandere.plekimportOmaclassGran():passclassDad(Gran):passclassMom(Oma):passclassSon(Dad,Mom):passforclsinAncestors(Son):print(cls.__name__)# prints out:# Son# Dad# Gran# Mom# OmaClass AncestorsAncestors(a_class: type, a_include_self: bool = True)An iterator for non-builtin ancestors of a classGoes recursively through all custom (i.e. not builtin) classes that
the base class inherits from. The base class itself comes first in the
iteration otherwise the order is unpredictable. Pass False as a second
argument to the constructor to avoid including the base class in the
iteration.Parametersa_classtypeThe base class, who's ancestors we want to iterate througha_include_selfbool, optionalIf True the base class itself is included in the iteration,
otherwise immedeatly proceeds to base class' ancestors. Defaults
to TrueModule iwp3tb.multitonA set of handy decorators for my beloved Singleton and Multiton design patterns.ConceptA multiton here is an abstract class, that has a finite number of
implementations. Each implementation is instantiated just once and this
instance is made available as an attribute of the parent multiton
class.A singleton is basically a multiton that has only one implementation.
Thus no need to separate the abstract class from private
implementation.This approach allows for very private implementations while
only the common interface becomes public.ExamplesBasic Multitonfromiwp3tbimportmultiton,implementation@multitonclassPowerRaiser():defraise_to_power(self,x:float)->float:# This is an abstract method.# Implementations should realise it.raiseException('You should have implemented this!')@implementationclassSecond(PowerRaiser):defraise_to_power(self,x):returnx*x@implementationclassThird(PowerRaiser):defraise_to_power(self,x):returnx*x*xprint(PowerRaiser.Second.raise_to_power(3))# prints out:# 9print(PowerRaiser.Third.raise_to_power(3))# prints out:# 27Custom MultitonArbitrary instance names can be used.fromiwp3tbimportmultiton,implementation_named@multitonclassPowerRaiser():defraise_to_power(self,x:float)->float:# This is an abstract method.# Implementations should realise it.raiseException('You should have implemented this!')@implementation_named('power2')classSecond(PowerRaiser):defraise_to_power(self,x):returnx*x@implementation_named('power3')classThird(PowerRaiser):defraise_to_power(self,x):returnx*x*xprint(PowerRaiser.power2.raise_to_power(3))# prints out:# 9print(PowerRaiser.power3.raise_to_power(3))# prints out:# 27Singletonfromiwp3tbimportsingleton@singletonclassSquarer():defto_square(self,x:float)->float:returnx*xprint(Squarer.instance.to_square(3))# prints out:# 9Function implementationimplementation(cls)Class decorator that registers an implementation with a multiton
ancestor class. Class name is used for the implementation instance name.
The class name must not conflict with any of the multition attributes.Function implementation_namedimplementation_named(a_name)Class decorator that registers an implementation with a multiton
ancestor class using a custom instance name. The class name must not
conflict with any of the multition attributes.Function multitonmultiton(cls)Class decorator for multiton. A multiton class should have no multition
or singleton ancestors.Function singletonsingleton(cls)Class decorator for singleton. A singleton class should have no
multition or singleton ancestors.Class MultitonErrorMultitonError(a_string)Common base class for multiton fatal errors.Ancestorsbuiltins.Exceptionbuiltins.BaseExceptionDescendantsiwp3tb.multiton.AlreadyHasRegistrarParentiwp3tb.multiton.NoRegistrarParentiwp3tb.multiton.RegistrarAlreadyHasAttributeClass NoRegistrarParentNoRegistrarParent(a_class)An error raised if a class is decorated as an implementation but it has no
multiton parent.fromiwp3tbimportimplementation@implementationclassBadImplementation():pass# Raises NoRegistrarParentAncestorsiwp3tb.multiton.MultitonErrorbuiltins.Exceptionbuiltins.BaseExceptionClass AlreadyHasRegistrarParentAlreadyHasRegistrarParent(a_class, a_registrar)An error raised if a class is decorated as an multiton but it already has a
multiton parent.fromiwp3tbimportmultiton@multitonclassGoodMultiton():pass@multitonclassBadMultiton(GoodMultiton):pass# Raises AlreadyHasRegistrarParentAncestorsiwp3tb.multiton.MultitonErrorbuiltins.Exceptionbuiltins.BaseExceptionClass RegistrarAlreadyHasAttributeRegistrarAlreadyHasAttribute(a_class, a_registrar, a_name)An error raised if a naming conflict happens while registering an implementation
with a multiton.fromiwp3tbimportmultiton,implementation,implementation_named@multitonclassGoodMultiton():pass@implementationclassGoodImplementation(GoodMultiton):pass@implementation_named('GoodImplementation')classBadImplementation(GoodMultiton):pass# Raises RegistrarAlreadyHasAttributeAncestorsiwp3tb.multiton.MultitonErrorbuiltins.Exceptionbuiltins.BaseExceptionToolsDocs generatorgendocs.shGenerates html documentation from source files usingpdocand saves it todocs/dir. Also
callscook_combined_md.pyto generate MarkDown version of the documentation
and then inserts it intoREADME.md(this file).Pdoc Virtual EnvironmentIf you point thePDOC_PYENVenvironment variable to a Python venv with pdoc
installed in it then all documentation generation will take place in this
virtual environment.Pdoc TemplatesTemplates frompdoc_templates/are used to generate documentation.
Alternatively you can setPDOC_TEMPLATESenvironment variable to point to an
alternative templates dir.Unit Testsruntests.shRuns unit tests.