diff options
Diffstat (limited to 'factory/base.py')
| -rw-r--r-- | factory/base.py | 406 |
1 files changed, 227 insertions, 179 deletions
diff --git a/factory/base.py b/factory/base.py index 3c6571c..0f2af59 100644 --- a/factory/base.py +++ b/factory/base.py @@ -1,6 +1,6 @@ # -*- coding: utf-8 -*- # Copyright (c) 2010 Mark Sandstrom -# Copyright (c) 2011-2013 Raphaël Barrois +# Copyright (c) 2011-2015 Raphaël Barrois # # Permission is hereby granted, free of charge, to any person obtaining a copy # of this software and associated documentation files (the "Software"), to deal @@ -23,6 +23,7 @@ import logging from . import containers +from . import declarations from . import utils logger = logging.getLogger('factory.generate') @@ -33,22 +34,13 @@ CREATE_STRATEGY = 'create' STUB_STRATEGY = 'stub' -# Special declarations -FACTORY_CLASS_DECLARATION = 'FACTORY_FOR' - -# Factory class attributes -CLASS_ATTRIBUTE_DECLARATIONS = '_declarations' -CLASS_ATTRIBUTE_POSTGEN_DECLARATIONS = '_postgen_declarations' -CLASS_ATTRIBUTE_ASSOCIATED_CLASS = '_associated_class' -CLASS_ATTRIBUTE_IS_ABSTRACT = '_abstract_factory' - class FactoryError(Exception): """Any exception raised by factory_boy.""" class AssociatedClassError(FactoryError): - """Exception for Factory subclasses lacking FACTORY_FOR.""" + """Exception for Factory subclasses lacking Meta.model.""" class UnknownStrategy(FactoryError): @@ -66,6 +58,14 @@ def get_factory_bases(bases): return [b for b in bases if issubclass(b, BaseFactory)] +def resolve_attribute(name, bases, default=None): + """Find the first definition of an attribute according to MRO order.""" + for base in bases: + if hasattr(base, name): + return getattr(base, name) + return default + + class FactoryMetaClass(type): """Factory metaclass for handling ordered declarations.""" @@ -75,142 +75,193 @@ class FactoryMetaClass(type): Returns an instance of the associated class. """ - if cls.FACTORY_STRATEGY == BUILD_STRATEGY: + if cls._meta.strategy == BUILD_STRATEGY: return cls.build(**kwargs) - elif cls.FACTORY_STRATEGY == CREATE_STRATEGY: + elif cls._meta.strategy == CREATE_STRATEGY: return cls.create(**kwargs) - elif cls.FACTORY_STRATEGY == STUB_STRATEGY: + elif cls._meta.strategy == STUB_STRATEGY: return cls.stub(**kwargs) else: - raise UnknownStrategy('Unknown FACTORY_STRATEGY: {0}'.format( - cls.FACTORY_STRATEGY)) + raise UnknownStrategy('Unknown Meta.strategy: {0}'.format( + cls._meta.strategy)) - @classmethod - def _discover_associated_class(mcs, class_name, attrs, inherited=None): - """Try to find the class associated with this factory. + def __new__(mcs, class_name, bases, attrs): + """Record attributes as a pattern for later instance construction. - In order, the following tests will be performed: - - Lookup the FACTORY_CLASS_DECLARATION attribute - - If an inherited associated class was provided, use it. + This is called when a new Factory subclass is defined; it will collect + attribute declaration from the class definition. Args: - class_name (str): the name of the factory class being created - attrs (dict): the dict of attributes from the factory class + class_name (str): the name of the class being created + bases (list of class): the parents of the class being created + attrs (str => obj dict): the attributes as defined in the class definition - inherited (class): the optional associated class inherited from a - parent factory Returns: - class: the class to associate with this factory + A new class """ - if FACTORY_CLASS_DECLARATION in attrs: - return attrs[FACTORY_CLASS_DECLARATION] + parent_factories = get_factory_bases(bases) + if parent_factories: + base_factory = parent_factories[0] + else: + base_factory = None - # No specific associated class was given, and one was defined for our - # parent, use it. - if inherited is not None: - return inherited + attrs_meta = attrs.pop('Meta', None) - # Nothing found, return None. - return None + base_meta = resolve_attribute('_meta', bases) + options_class = resolve_attribute('_options_class', bases, FactoryOptions) - @classmethod - def _extract_declarations(mcs, bases, attributes): - """Extract declarations from a class definition. + meta = options_class() + attrs['_meta'] = meta - Args: - bases (class list): parent Factory subclasses - attributes (dict): attributes declared in the class definition + new_class = super(FactoryMetaClass, mcs).__new__( + mcs, class_name, bases, attrs) - Returns: - dict: the original attributes, where declarations have been moved to - _declarations and post-generation declarations to - _postgen_declarations. - """ - declarations = containers.DeclarationDict() - postgen_declarations = containers.PostGenerationDeclarationDict() + meta.contribute_to_class(new_class, + meta=attrs_meta, + base_meta=base_meta, + base_factory=base_factory, + ) - # Add parent declarations in reverse order. - for base in reversed(bases): - # Import parent PostGenerationDeclaration - postgen_declarations.update_with_public( - getattr(base, CLASS_ATTRIBUTE_POSTGEN_DECLARATIONS, {})) - # Import all 'public' attributes (avoid those starting with _) - declarations.update_with_public( - getattr(base, CLASS_ATTRIBUTE_DECLARATIONS, {})) + return new_class - # Import attributes from the class definition - attributes = postgen_declarations.update_with_public(attributes) - # Store protected/private attributes in 'non_factory_attrs'. - attributes = declarations.update_with_public(attributes) + def __str__(cls): + if cls._meta.abstract: + return '<%s (abstract)>' % cls.__name__ + else: + return '<%s for %s>' % (cls.__name__, cls._meta.model) - # Store the DeclarationDict in the attributes of the newly created class - attributes[CLASS_ATTRIBUTE_DECLARATIONS] = declarations - attributes[CLASS_ATTRIBUTE_POSTGEN_DECLARATIONS] = postgen_declarations - return attributes +class BaseMeta: + abstract = True + strategy = CREATE_STRATEGY - def __new__(mcs, class_name, bases, attrs): - """Record attributes as a pattern for later instance construction. - This is called when a new Factory subclass is defined; it will collect - attribute declaration from the class definition. +class OptionDefault(object): + def __init__(self, name, value, inherit=False): + self.name = name + self.value = value + self.inherit = inherit - Args: - class_name (str): the name of the class being created - bases (list of class): the parents of the class being created - attrs (str => obj dict): the attributes as defined in the class - definition - - Returns: - A new class - """ - parent_factories = get_factory_bases(bases) - if not parent_factories: - return super(FactoryMetaClass, mcs).__new__( - mcs, class_name, bases, attrs) - - extra_attrs = {} + def apply(self, meta, base_meta): + value = self.value + if self.inherit and base_meta is not None: + value = getattr(base_meta, self.name, value) + if meta is not None: + value = getattr(meta, self.name, value) + return value - is_abstract = attrs.pop('ABSTRACT_FACTORY', False) + def __str__(self): + return '%s(%r, %r, inherit=%r)' % ( + self.__class__.__name__, + self.name, self.value, self.inherit) - base = parent_factories[0] - inherited_associated_class = base._get_target_class() - associated_class = mcs._discover_associated_class(class_name, attrs, - inherited_associated_class) - # Invoke 'lazy-loading' hooks. - associated_class = base._load_target_class(associated_class) +class FactoryOptions(object): + def __init__(self): + self.factory = None + self.base_factory = None + self.declarations = {} + self.postgen_declarations = {} - if associated_class is None: - is_abstract = True + def _build_default_options(self): + """"Provide the default value for all allowed fields. + Custom FactoryOptions classes should override this method + to update() its return value. + """ + return [ + OptionDefault('model', None, inherit=True), + OptionDefault('abstract', False, inherit=False), + OptionDefault('strategy', CREATE_STRATEGY, inherit=True), + OptionDefault('inline_args', (), inherit=True), + OptionDefault('exclude', (), inherit=True), + OptionDefault('rename', {}, inherit=True), + ] + + def _fill_from_meta(self, meta, base_meta): + # Exclude private/protected fields from the meta + if meta is None: + meta_attrs = {} else: - # If inheriting the factory from a parent, keep a link to it. - # This allows to use the sequence counters from the parents. - if (inherited_associated_class is not None - and issubclass(associated_class, inherited_associated_class)): - attrs['_base_factory'] = base + meta_attrs = dict((k, v) + for (k, v) in vars(meta).items() + if not k.startswith('_') + ) + + for option in self._build_default_options(): + assert not hasattr(self, option.name), "Can't override field %s." % option.name + value = option.apply(meta, base_meta) + meta_attrs.pop(option.name, None) + setattr(self, option.name, value) + + if meta_attrs: + # Some attributes in the Meta aren't allowed here + raise TypeError("'class Meta' for %r got unknown attribute(s) %s" + % (self.factory, ','.join(sorted(meta_attrs.keys())))) + + def contribute_to_class(self, factory, + meta=None, base_meta=None, base_factory=None): + + self.factory = factory + self.base_factory = base_factory + + self._fill_from_meta(meta=meta, base_meta=base_meta) + + self.model = self.factory._load_model_class(self.model) + if self.model is None: + self.abstract = True + + self.counter_reference = self._get_counter_reference() + + for parent in reversed(self.factory.__mro__[1:]): + if not hasattr(parent, '_meta'): + continue + self.declarations.update(parent._meta.declarations) + self.postgen_declarations.update(parent._meta.postgen_declarations) + + for k, v in vars(self.factory).items(): + if self._is_declaration(k, v): + self.declarations[k] = v + if self._is_postgen_declaration(k, v): + self.postgen_declarations[k] = v + + def _get_counter_reference(self): + """Identify which factory should be used for a shared counter.""" + + if (self.model is not None + and self.base_factory is not None + and self.base_factory._meta.model is not None + and issubclass(self.model, self.base_factory._meta.model)): + return self.base_factory + else: + return self.factory - # The CLASS_ATTRIBUTE_ASSOCIATED_CLASS must *not* be taken into - # account when parsing the declared attributes of the new class. - extra_attrs[CLASS_ATTRIBUTE_ASSOCIATED_CLASS] = associated_class + def _is_declaration(self, name, value): + """Determines if a class attribute is a field value declaration. - extra_attrs[CLASS_ATTRIBUTE_IS_ABSTRACT] = is_abstract + Based on the name and value of the class attribute, return ``True`` if + it looks like a declaration of a default field value, ``False`` if it + is private (name starts with '_') or a classmethod or staticmethod. - # Extract pre- and post-generation declarations - attributes = mcs._extract_declarations(parent_factories, attrs) - attributes.update(extra_attrs) + """ + if isinstance(value, (classmethod, staticmethod)): + return False + elif isinstance(value, declarations.OrderedDeclaration): + return True + elif isinstance(value, declarations.PostGenerationDeclaration): + return False + return not name.startswith("_") - return super(FactoryMetaClass, mcs).__new__( - mcs, class_name, bases, attributes) + def _is_postgen_declaration(self, name, value): + """Captures instances of PostGenerationDeclaration.""" + return isinstance(value, declarations.PostGenerationDeclaration) - def __str__(cls): - if cls._abstract_factory: - return '<%s (abstract)>' - else: - return '<%s for %s>' % (cls.__name__, - getattr(cls, CLASS_ATTRIBUTE_ASSOCIATED_CLASS).__name__) + def __str__(self): + return "<%s for %s>" % (self.__class__.__name__, self.factory.__class__.__name__) + + def __repr__(self): + return str(self) # Factory base classes @@ -252,26 +303,11 @@ class BaseFactory(object): """Would be called if trying to instantiate the class.""" raise FactoryError('You cannot instantiate BaseFactory') + _meta = FactoryOptions() + # ID to use for the next 'declarations.Sequence' attribute. _counter = None - # Base factory, if this class was inherited from another factory. This is - # used for sharing the sequence _counter among factories for the same - # class. - _base_factory = None - - # Holds the target class, once resolved. - _associated_class = None - - # Whether this factory is considered "abstract", thus uncallable. - _abstract_factory = False - - # List of arguments that should be passed as *args instead of **kwargs - FACTORY_ARG_PARAMETERS = () - - # List of attributes that should not be passed to the underlying class - FACTORY_HIDDEN_ARGS = () - @classmethod def reset_sequence(cls, value=None, force=False): """Reset the sequence counter. @@ -282,9 +318,9 @@ class BaseFactory(object): force (bool): whether to force-reset parent sequence counters in a factory inheritance chain. """ - if cls._base_factory: + if cls._meta.counter_reference is not cls: if force: - cls._base_factory.reset_sequence(value=value) + cls._meta.base_factory.reset_sequence(value=value) else: raise ValueError( "Cannot reset the sequence of a factory subclass. " @@ -330,9 +366,9 @@ class BaseFactory(object): """ # Rely upon our parents - if cls._base_factory and not cls._base_factory._abstract_factory: - logger.debug("%r: reusing sequence from %r", cls, cls._base_factory) - return cls._base_factory._generate_next_sequence() + if cls._meta.counter_reference is not cls: + logger.debug("%r: reusing sequence from %r", cls, cls._meta.base_factory) + return cls._meta.base_factory._generate_next_sequence() # Make sure _counter is initialized cls._setup_counter() @@ -373,7 +409,15 @@ class BaseFactory(object): extra_defs (dict): additional definitions to insert into the retrieved DeclarationDict. """ - return getattr(cls, CLASS_ATTRIBUTE_DECLARATIONS).copy(extra_defs) + decls = cls._meta.declarations.copy() + decls.update(extra_defs or {}) + return decls + + @classmethod + def _rename_fields(cls, **kwargs): + for old_name, new_name in cls._meta.rename.items(): + kwargs[new_name] = kwargs.pop(old_name) + return kwargs @classmethod def _adjust_kwargs(cls, **kwargs): @@ -381,8 +425,8 @@ class BaseFactory(object): return kwargs @classmethod - def _load_target_class(cls, class_definition): - """Extension point for loading target classes. + def _load_model_class(cls, class_definition): + """Extension point for loading model classes. This can be overridden in framework-specific subclasses to hook into existing model repositories, for instance. @@ -390,10 +434,10 @@ class BaseFactory(object): return class_definition @classmethod - def _get_target_class(cls): - """Retrieve the actual, associated target class.""" - definition = getattr(cls, CLASS_ATTRIBUTE_ASSOCIATED_CLASS, None) - return cls._load_target_class(definition) + def _get_model_class(cls): + """Retrieve the actual, associated model class.""" + definition = cls._meta.model + return cls._load_model_class(definition) @classmethod def _prepare(cls, create, **kwargs): @@ -403,15 +447,16 @@ class BaseFactory(object): create: bool, whether to create or to build the object **kwargs: arguments to pass to the creation function """ - target_class = cls._get_target_class() + model_class = cls._get_model_class() + kwargs = cls._rename_fields(**kwargs) kwargs = cls._adjust_kwargs(**kwargs) # Remove 'hidden' arguments. - for arg in cls.FACTORY_HIDDEN_ARGS: + for arg in cls._meta.exclude: del kwargs[arg] # Extract *args from **kwargs - args = tuple(kwargs.pop(key) for key in cls.FACTORY_ARG_PARAMETERS) + args = tuple(kwargs.pop(key) for key in cls._meta.inline_args) logger.debug('BaseFactory: Generating %s.%s(%s)', cls.__module__, @@ -419,9 +464,9 @@ class BaseFactory(object): utils.log_pprint(args, kwargs), ) if create: - return cls._create(target_class, *args, **kwargs) + return cls._create(model_class, *args, **kwargs) else: - return cls._build(target_class, *args, **kwargs) + return cls._build(model_class, *args, **kwargs) @classmethod def _generate(cls, create, attrs): @@ -431,15 +476,14 @@ class BaseFactory(object): create (bool): whether to 'build' or 'create' the object attrs (dict): attributes to use for generating the object """ - if cls._abstract_factory: + if cls._meta.abstract: raise FactoryError( "Cannot generate instances of abstract factory %(f)s; " - "Ensure %(f)s.FACTORY_FOR is set and %(f)s.ABSTRACT_FACTORY " - "is either not set or False." % dict(f=cls)) + "Ensure %(f)s.Meta.model is set and %(f)s.Meta.abstract " + "is either not set or False." % dict(f=cls.__name__)) # Extract declarations used for post-generation - postgen_declarations = getattr(cls, - CLASS_ATTRIBUTE_POSTGEN_DECLARATIONS) + postgen_declarations = cls._meta.postgen_declarations postgen_attributes = {} for name, decl in sorted(postgen_declarations.items()): postgen_attributes[name] = decl.extract(name, attrs) @@ -469,34 +513,34 @@ class BaseFactory(object): pass @classmethod - def _build(cls, target_class, *args, **kwargs): - """Actually build an instance of the target_class. + def _build(cls, model_class, *args, **kwargs): + """Actually build an instance of the model_class. Customization point, will be called once the full set of args and kwargs has been computed. Args: - target_class (type): the class for which an instance should be + model_class (type): the class for which an instance should be built args (tuple): arguments to use when building the class kwargs (dict): keyword arguments to use when building the class """ - return target_class(*args, **kwargs) + return model_class(*args, **kwargs) @classmethod - def _create(cls, target_class, *args, **kwargs): - """Actually create an instance of the target_class. + def _create(cls, model_class, *args, **kwargs): + """Actually create an instance of the model_class. Customization point, will be called once the full set of args and kwargs has been computed. Args: - target_class (type): the class for which an instance should be + model_class (type): the class for which an instance should be created args (tuple): arguments to use when creating the class kwargs (dict): keyword arguments to use when creating the class """ - return target_class(*args, **kwargs) + return model_class(*args, **kwargs) @classmethod def build(cls, **kwargs): @@ -626,8 +670,7 @@ class BaseFactory(object): Factory = FactoryMetaClass('Factory', (BaseFactory,), { - 'ABSTRACT_FACTORY': True, - 'FACTORY_STRATEGY': CREATE_STRATEGY, + 'Meta': BaseMeta, '__doc__': """Factory base with build and create support. This class has the ability to support multiple ORMs by using custom creation @@ -642,12 +685,13 @@ Factory.AssociatedClassError = AssociatedClassError # pylint: disable=W0201 class StubFactory(Factory): - FACTORY_STRATEGY = STUB_STRATEGY - FACTORY_FOR = containers.StubObject + class Meta: + strategy = STUB_STRATEGY + model = containers.StubObject @classmethod def build(cls, **kwargs): - raise UnsupportedStrategy() + return cls.stub(**kwargs) @classmethod def create(cls, **kwargs): @@ -656,44 +700,48 @@ class StubFactory(Factory): class BaseDictFactory(Factory): """Factory for dictionary-like classes.""" - ABSTRACT_FACTORY = True + class Meta: + abstract = True @classmethod - def _build(cls, target_class, *args, **kwargs): + def _build(cls, model_class, *args, **kwargs): if args: raise ValueError( - "DictFactory %r does not support FACTORY_ARG_PARAMETERS.", cls) - return target_class(**kwargs) + "DictFactory %r does not support Meta.inline_args.", cls) + return model_class(**kwargs) @classmethod - def _create(cls, target_class, *args, **kwargs): - return cls._build(target_class, *args, **kwargs) + def _create(cls, model_class, *args, **kwargs): + return cls._build(model_class, *args, **kwargs) class DictFactory(BaseDictFactory): - FACTORY_FOR = dict + class Meta: + model = dict class BaseListFactory(Factory): """Factory for list-like classes.""" - ABSTRACT_FACTORY = True + class Meta: + abstract = True @classmethod - def _build(cls, target_class, *args, **kwargs): + def _build(cls, model_class, *args, **kwargs): if args: raise ValueError( - "ListFactory %r does not support FACTORY_ARG_PARAMETERS.", cls) + "ListFactory %r does not support Meta.inline_args.", cls) values = [v for k, v in sorted(kwargs.items())] - return target_class(values) + return model_class(values) @classmethod - def _create(cls, target_class, *args, **kwargs): - return cls._build(target_class, *args, **kwargs) + def _create(cls, model_class, *args, **kwargs): + return cls._build(model_class, *args, **kwargs) class ListFactory(BaseListFactory): - FACTORY_FOR = list + class Meta: + model = list def use_strategy(new_strategy): @@ -702,6 +750,6 @@ def use_strategy(new_strategy): This is an alternative to setting default_strategy in the class definition. """ def wrapped_class(klass): - klass.FACTORY_STRATEGY = new_strategy + klass._meta.strategy = new_strategy return klass return wrapped_class |