Metadata-Version: 1.0
Name: fixturefactory
Version: 0.1
Summary: Factory to generate Django model objects.  Easier than factoryboy and factorygirl
Home-page: git@github.com:adgaudio/fixturefactory.git
Author: Alex Gaudio
Author-email: adgaudio@gmail.com
License: UNKNOWN
Description: About:
        ===
        
        fixturefactory is a super simple, easy to use and customizable library for creating Django fixtures.  
        
        Within fixturefactory.py, you will find a BaseFactory and DjangoMixin.
        
        * The BaseFactory class was written to make developing with factories for other purposes or frameworks very simple.
        * The DjangoMixin class provides some methods to make fixture creation easy.
        
        Please fork, give feedback, or add an issue to the tracker!
        
        Use Cases:
        ===
        
        Creating instances of a model
        
            >>> ChildFactory()
            >>> ChildFactory(save_to_db=False)
        
        Dynamically passing params to your factories
        
            >>> child1 = ChildFactory().last_obj_created
            
            >>> BrotherFactory(pk1=child1.pk, pk2=1) # These pks are usable as class vars
        
        
        Defining your Factories:
        ===
        
        All factories you create need to have these basic characteristics:
        
        * Must inherit from BaseFactory (should also inherit from DjangoMixin to simplify working with Django)
        * Must have a class variable, 'model', which works like this: inst = model(some='keyword args') ; inst.save() # to db
        * Must have a method, 'getparams', which returns a dict containing the params necessary to instantiate the model.
        
        The basic template looks like this:
        
            class ChildFactory(BaseFactory, DjangoMixin):
                model = myapp.models.SomeModel
        
                def getparams(self): return {}
        
        
        Example Implementations:
        ---
        
        The following factory generates generic Django users.  A more advanced implementation may make use of randomly generated text, etc.  Note that getparams returns locals(), which is a dict of the local environment.  If you have defined temporary variables in the getparams() method, this approach can cause django to raise an exception, but it also brings up the point that getparams() should not do anything complicated.  The purpose of getparams() is to define parameters that will eventually get sent as a call to your factory's model
        
            class UserFactory(BaseFactory, DjangoMixin):
                model = django.contrib.auth.models.User
        
                def getparams(self):
                    pk = self.getUnusedPk() # Utilize the methods in DjangoMixin
                    username = 'markov_%s' % pk
                    password = username
                    return locals()
        
        This next example shows how to implement Foreign Keys, where the UserProfile has a Foreign Key on the above example's User model.  Note that the 'user' variable in getparams() is an instance of the UserFactory's model 
        
            class UserProfileFactory(BaseFactory, DjangoMixin):
                model = myapp.models.UserProfile
        
                def getparams(self):
                    """An example of a foreign key"""
                    user = UserFactory().last_obj_created
                    pk = user.pk #this User and UserProfile share the same primary key
                    return locals()
        
        Implementing Many to Many Relationships are also very easy. In this example, lets assume that RelatedUser is a many to many table linking Users to each other.  Use this simple form if you don't care about which 2 UserProfiles the relationships are between:
        
            class RelatedUserFactory(BaseFactory, DjangoMixin):
                model = myapp.models.RelatedUser
                def getparams(self):
                    user1_id = self.getRandInst(myapp.models.UserProfile).pk
                    user2_id = self.getRandInst(myapp.models.UserProfile).pk
                    return locals()
        
        If you wanted to link 2 user profiles dynamically at runtime, your factory might look a little different. 
        
            class RelatedUserFactory(BaseFactory, DjangoMixin):
                model = myapp.models.RelatedUser
        
                def getparams(self):
                    user1 = self.pk1 #NOTE the use of self.pk1 and self.pk2
                    user2 = self.pk2
                    return locals()
        
            >>> RelatedUserFactory(pk1=3, pk2=5) #keyword param required in this case.
        
        You can avoid typing in keyword arguments if you really want to by overriding the init method.  If you do this, which probably means you're overthinking things a bit, make sure you call super() **at the end** of your init method like so:
        
                def __init__(self, pk1, pk2):
                    self.pk1 = pk1
                    self.pk2 = pk2
                    super(self.__class__, self).__init__()
        
        Also, you can have your factory fall back to randomly choosing values if no keyword argument is supplied by setting class variables to None before __init__ gets called.
        
            class RelatedUserFactory(BaseFactory, DjangoMixin):
                model = mysapp.models.RelatedUser
        
                pk1 = None # sets default value
                pk2 = None
        
                def getparams(self):
                    user1 = self.pk1 or self.getRandInst(myapp.models.UserProfile).pk
                    user2 = self.pk2 or self.getRandInst(myapp.models.UserProfile).pk
        
        Development:
        ===
        
        To use BaseFactory for a purpose other than Django fixtures, you'd have to (probably) override the BaseFactory.create() method.  You will also probably want to create a mixin to simplify development (see DjangoMixin for an example).
        
        I hope all this encourages you to use fixturefactory!
        
Keywords: django factory fixture
Platform: UNKNOWN
