Imagination Documentation

Transcription

1 Imagination Documentation Release 1.5 Juti Noppornpitak July 01, 2013

2

3 CONTENTS i

4 ii

5 Copyright Juti Noppornpitak Author Juti Noppornpitak License MIT Imagination is a reusable component framework whose objectives are: encapsulates an object into a single object with the lazy loader, inspired by many frameworks (e.g., Symfony Framework in PHP and Spring Framework in Java), improves code maintainability by encapsulating reusable components (or dependencies) in a global memory, inspired by JavaBeans, introduce the concept of the aspect-oriented programming (AOP), inspired by AspectJ. Want to get started? Please read Getting Started. Note: Imagination plays the big role in Tori Web Framework ( dealing with clean routing and globally referencing to any defined reusable components. CONTENTS 1

6 2 CONTENTS

7 CHAPTER ONE HOW TO INSTALL Python 3.3 3

8 4 Chapter 1. How to Install

9 CHAPTER TWO RELEASES Development Version Support Python 3.3 Add a point cut Version 1.5 Added support for aspect-oriented programming and introduced some backward incompatibility. Version 1.0 Simple object collection repository 5

10 6 Chapter 2. Releases

11 CHAPTER THREE REFERENCE 3.1 Getting Started Author Juti Noppornpitak As I am a lazy lad, I will guide you, the reader, through the framework with this example. Note: This example is based on the actual test Simple Setup Then, we also have the code base as followed: stage-app/ main.py <-- this is the main script to bootstrap and run this app. imagination.xml restaurant.py where main.py has the following content while using Imagination 1.5 or higher: # Imagination 1.5+ from imagination.helper.assembler import Assembler from imagination.helper.data import Transformer from imagination.locator import Locator locator = Locator() # pretty much like entity manager transformer = Transformer(locator) # data transformer as a mandatory extension for Assembler assembler = Assembler(transformer) assembler.load( imagination.xml ) or the following one with Imagination 1.0: # Imagination 1.0 from imagination.locator import Locator locator = Locator() locator.load_xml( imagination.xml ) # Imagination 7

12 3.1.2 Advanced Setup with Aspect-oriented Programming Warning: This section is applicable with Imagination 1.5 or higher. First of all, let s define two actors (entity) in this story: alpha as a customer and charlie as a chef/server. <?xml version="1.0" encoding="utf-8"?> <imagination> <entity id="alpha" class="restaurant.alpha"> <param type="entity" name="accompany">beta</param> </entity> <entity id="charlie" class="restaurant.charlie"/> </imagination> With this, in the code, we can get any of the actors by: alpha = locator.get( alpha ) # to get "alpha". Then, suppose that before charlie cooks, he needs to listen when customers want to eat. In the old fashion way, we might have done.: # restaurant.py class Charlie(object): # entity "charlie" # anything before... def cook(self): order = [] order.append(alpha.order()) # "egg and becon" # do cooking... # anthing after... # main.py locator.get( charlie ).take_care(locator.get( alpha )) locator.get( charlie ).cook() or: # main.py locator.get( charlie ).take_order(locator.get( alpha ).order()) locator.get( charlie ).cook() Note: Assume that charlie has methods take_care or take_order and alpha has a method order. Well, it works but Charlie needs to know alpha. What if there are more people added into the story. Then, the code will become unnecessarily messy. Let s apply AOP then. By doing that, first, Charlie is slightly modified. class Charlie(object): # entity "charlie" # anything before... def cook(self): # do cooking... 8 Chapter 3. Reference

13 # anthing after... Then, in imagination.xml, we now add interceptions. <?xml version="1.0" encoding="utf-8"?> <imagination> <entity id="alpha" class="restaurant.alpha"> <param type="entity" name="accompany">beta</param> <interception before="charlie" do="cook" with="order"> <param type="unicode" name="item">egg and becon</param> </interception> </entity> <entity id="charlie" class="restaurant.charlie"/> </imagination> Finally, in main.py, we can just write: locator.get( charlie ).cook() On execution, assuming that alpha sends the order to the central queue, alpha will intercept before charlie cook by ordering egg and becon. Then, charlie will take the order from the central queue. Note: Read Assembler for the configuration specification. Now, eventually, we have the cleaner code that do exactly what we want in the more maintainable way. 3.2 imagination.action Author Juti Noppornpitak Version 1.5 Usage Internal The module contains the classes used for interceptable actions/methods of any instance of imagination.entity.entity. Note: Copyright (c) 2012 Juti Noppornpitak 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 PAR- TICULAR 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 SOFT- WARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE imagination.action 9

14 class imagination.action.action(*args, **kwargs) Method wrapper for intercepting actions name Name of the action reference Reference of the action class imagination.action.eventtype Type of intercepting events post_action = after Event after the execution that doesn t care about the returned value from the action. post_condition = post Event after the execution that only concerns about the returned value from the action. pre_action = before Event before the execution that doesn t care about the input given to the action. pre_condition = pre Event before the execution that only concerns about the input given to the action Supplementary documentation Because Sphinx doesn t know how to interpret the doc block of any methods with imagination.decorator.validator.restrict_type(), this section serves as a missing documentation. imagination.action.action.register(interception) Register the interception for this action. Parameters interception (imagination.meta.interception.interception) the metadata for the interception 3.3 imagination.decorator.validator Author Juti Noppornpitak Availability 1.5 The module contains reusable input validators. Note: Copyright (c) 2012 Juti Noppornpitak 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 PAR- TICULAR 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 10 Chapter 3. Reference

15 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFT- WARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. imagination.decorator.validator.restrict_type(*restricted_list, **restricted_map) The method decorator to validate the type of inputs given to the method. Parameters restricted_list the list of types to restrict the type of each parameter in the same order as the parameter given to the method. restricted_map the map of types to restrict the type of each parameter by name. When the input fails the validation, an exception of type TypeError is throw. There are a few exceptions: If the given type is None, there will be no restriction. If the given type is long, the value of int and float are also valid. If the given type is unicode, the valud of str is also valid. Warning: In Imagination 1.6, types unicode and long are no longer have fallback check in order to support Python 3.3. from imagination.decorator.validator import restrict_type # Example on a def say(context): print context class Person(object): # Example on a int) def init (self, name, age): self.name = name self.age = age self. friends = [] # Example on an instance def add_friend(self, person): self. friends.append(person) 3.4 imagination.entity Author Juti Noppornpitak The module contains the package entity used to be an intermediate between imagination.locator.locator and imagination.loader.loader and simulate the singleton class on the package in the Loader. Note: Copyright (c) 2012 Juti Noppornpitak 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, 3.4. imagination.entity 11

16 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 PAR- TICULAR 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 SOFT- WARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. class imagination.entity.entity(*args, **kwargs) Entity represents the package, reference and instance of the reference. Parameters id the service identifier (string). loader a service loader which is an instance of imagination.loader.loader. args (dict) constructor s parameters kwargs constructor s parameters If the loader is not an instance of imagination.loader.loader or any classes based on imagination.loader.loader, the exception imagination.exception.unknownloadererror will be thrown. Note: This class is to similar to the decorator tori.decorator.common.singleton and tori.decorator.common.singleton_with from Tori Framework, except that it is not a singleton class and so any arbitrary class referenced by the loader only lasts as long as the entity lives. Note: In version 1.5, the entity has the ability to fork an non-supervised instance of the reference. activated Check if the entity is already activated. This will also inspects if the entity already loads a singleton instance into the memory. argument_dictionary Get the argument dictionary. argument_list Get the argument list. fork() id Version 1.5 Fork an instance of the class defined for the loader. Entity ID Return type strint or unicode or integer instance Get the singleton instance of the class defined for the loader. 12 Chapter 3. Reference

17 interceptable Flag if this entity is interceptable Return type boolean interceptions Retrieve the list of interceptions. loader Package loader Return type imagination.loader.loader tags Retrieve the entity tags. Return type list 3.5 imagination.exception exception imagination.exception.deprecatedapi Exception thrown when a deprecated API is used. exception imagination.exception.duplicatekeywarning Warning thrown when an internal dictionary detects an attempt of re-assignment to the direction by the existed key. exception imagination.exception.forbiddenforkerror Exception thrown only when a locator try to fork a proxy. exception imagination.exception.incompatibleblockerror Exception thrown when imagination.locator.locator.load_xml() cannot process the entity block. exception imagination.exception.lockedentityexception Exception thrown when a caller attempts to update any of alterable properties of an instance of imagination.entity.entity when it is in the locked state. exception imagination.exception.misplacedvalidatorerror Exception thrown when a validator is used with type (e.g., class, perimitive types etc.) exception imagination.exception.multipleinterceptingeventswarning Warning thrown when more than one intercepting event is detected. exception imagination.exception.noncallableerror Exception thrown when imagination.action.action tries to execute a non-callable reference. exception imagination.exception.unknownentityerror Exception thrown when imagination.locator.locator constructor receives an unusable entity. exception imagination.exception.unknownfileerror Exception thrown when imagination.locator.locator.load_xml() cannot locate the file on the given path. exception imagination.exception.unknownproxyerror Exception thrown when imagination.helper.assembler.assembler could not find the proxy imagination.exception 13

18 3.6 Assembler Module imagination.helper.assembler Author Juti Noppornpitak Dependency kotoba 3.0 Availability 1.5 The module contains the assembler to constuct loaders and entites based on the configuration and register to a particular locator XML Schema Note: This is the master specification document for the configuration. The schema is defined as followed: # Base <imagination> (ENTITY)* </imagination> # Entity ENTITY = <entity id="entity_id" class="entity_class" (interceptable="(true false)")? (option=entity_options)? > (CONSTRUCTOR_PARAMETER)* (INTERCEPTION)* </entity> ENTITY_OPTIONS=(factory-mode) # Constructor s parameter and initial parameter CONSTRUCTOR_PARAMETER = INITIAL_PARAMETER = <parameter type="parameter_type" name="parameter_name"> (PARAMETER_VALUE ENTITY_ID CLASS_IDENTIFIER) </parameter> # See the section "Parameter Types" for PARAMETER_TYPE. # Event EVENT=(before pre post after) INTERCEPTION = <interception EVENT="REFERENCE_ENTITY_IDENTIFIER" do="reference_entity_method" with="this_entity_method" > (INITIAL_PARAMETER)* </interception> 14 Chapter 3. Reference

19 where: ENTITY_ID is the identifier of the entity. ENTITY_CLASS is the fully-qualified class name of the entity. (e.g. tori.service.rdb.entityservice) option is the option of the entity where ENTITY_OPTIONS can have one or more of: factory-mode: always fork the instance of the given class. no-interuption: any methods of the entity cannot be interrupted. REFERENCE_ENTITY_IDENTIFIER is the reference s entity identifier REFERENCE_ENTITY_METHOD is the reference s method name THIS_ENTITY_METHOD is this entity s method name EVENT is where the REFERENCE_ENTITY_METHOD is intercepted. before is an event before the execution of the method of the reference (reference method) regardless to the given arguments to the reference method. pre is an event on pre-contact of the reference method and concerning about the arguments given to the reference method. The method of the entity (the intercepting method) takes the same paramenter as the reference method. post is an event on post-contact of the reference method and concerning about the result returned by the reference method. The intercepting method for this event takes only one parameter which is the result from the reference method or any previous post-contact interceptors. after is an event after the execution of the reference method regardless to the result reterned by the reference method Parameter Types Type Data Type Name unicode Unicode (default) bool Boolean 1 float Float int Integer class Class reference 2 entity imagination.entity.entity Example <?xml version="1.0" encoding="utf-8"?> <imagination> <entity id="alpha" class="dummy.lazy_action.alpha"> <param type="entity" name="accompany">beta</param> <interception before="charlie" do="cook" with="order"> <param type="unicode" name="item">egg and becon</param> 1 Only any variations (letter case) of the word true or false are considered as a valid boolean value. 2 The module and package specified as the value of <param> is loaded when Assembler.load() is executed. 3 The encapsulated instance of the entity specified as the value of <param> is instantiated when Assembler.load() is executed or when the instance is given with a proxy (imagination.proxy.proxy) Assembler 15

20 </interception> <interception pre="charlie" do="repeat" with="confirm"/> <interception before="charlie" do="serve" with="speak_to_accompany"> <param type="str" name="context">watch your hand</param> </interception> <interception before="charlie" do="serve" with="wash_hands"/> <interception after="me" do="eat" with="speak"> <param type="str" name="context">merci</param> </interception> </entity> <entity id="beta" class="dummy.lazy_action.beta"/> <entity id="charlie" class="dummy.lazy_action.charlie"/> </imagination> Note: Copyright (c) 2012 Juti Noppornpitak 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 PAR- TICULAR 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 SOFT- WARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE API class imagination.helper.assembler.assembler(*args, **kwargs) The entity assembler via configuration files. Parameters transformer an instance of imagination.helper.data.transformer load(filepath) Load the configuration. Parameters filepath (string or unicode) the file path to the configuration. locator The injected locator via the data transformer. Return type imagination.locator.locator Supplementary documentation Because Sphinx doesn t know how to interpret the doc block of any methods with imagination.decorator.validator.restrict_type(), this section serves as a missing documentation. Assembler.load(filepath) Load the configuration. 16 Chapter 3. Reference

21 Parameters filepath (string or unicode) the file path to the configuration. 3.7 imagination.loader Author Juti Noppornpitak The module contains the package loader used to improve code maintainability. Note: Copyright (c) 2012 Juti Noppornpitak 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 PAR- TICULAR 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 SOFT- WARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. class imagination.loader.loader(path_to_package) Package loader with lazy loading path_to_package is a string representing the package path. For example: # In this case, we load the default renderer of Tori framework. loader = Loader( tori.renderer.defaultrenderer ) # Then, instantiate the default renderer. renderer = loader.package( app.views ) filename Get the path to the package. module Get a reference to the module. name Get the name of the package. package Get a reference to the package. 3.8 imagination.locator Author Juti Noppornpitak The module contains the entity locator used to promote reusability of components imagination.loader 17

22 Note: Copyright (c) 2012 Juti Noppornpitak 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 PAR- TICULAR 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 SOFT- WARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. class imagination.locator.locator Entity locator find_by_tag(tag_label) Retrieve entities by tag_label. Parameters tag_label tag label fork(id) Fork the entity identified by id. Parameters id entity identifier get(id) Retrieve the entity identified by id. Parameters id entity identifier Returns the requested entity get_wrapper(id) Retrieve the entity wrapper identified by id. Parameters id entity identifier Returns the requested entity wrapper has(id) Check if the entity with id is already registered. load_xml(file_path) Load the entities from a XML configuration file at file_path. Status Deprecated in 1.5 set(id, entity) Set the given entity by id. 18 Chapter 3. Reference

23 PYTHON MODULE INDEX i imagination.action,?? imagination.decorator.validator,?? imagination.entity,?? imagination.exception,?? imagination.helper.assembler,?? imagination.loader,?? imagination.locator,?? 19