Object Reference

Errors module

exception service_objects.errors.InvalidInputsError(errors, non_field_errors)

Raised during Service’s service_clean() method. Encapsulates both field_errors and non_field_errors into a single entity.

Parameters:
  • errors (dictionary) – Services’s errors dictionary
  • non_field_errors (dictionary) – Service’s non_field_errors dictionary

Fields module

class service_objects.fields.DictField(*, required=True, widget=None, label=None, initial=None, help_text='', error_messages=None, show_hidden_initial=False, validators=(), localize=False, disabled=False, label_suffix=None)

A field for Service that accepts a dictionary:

class PDFGenerate(Service):

context = DictField()

process(self):
context = self.cleaned_data[‘context’]
PDFGenerate.execute({
‘context’: {‘a’: 1, ‘b’: 2}

})

clean(value)

Validate the given value and return its “cleaned” value as an appropriate Python object. Raise ValidationError for any errors.

class service_objects.fields.ListField(*, required=True, widget=None, label=None, initial=None, help_text='', error_messages=None, show_hidden_initial=False, validators=(), localize=False, disabled=False, label_suffix=None)

A field for Service that accepts a list:

class EmailWelcomeMessage(Service):

emails = ListField()

process(self):
emails = self.cleaned_data[‘emails’]
EmailWelcomeMessage.execute({
‘emails’: [‘blue@test.com’, ‘red@test.com’]

})

clean(value)

Validate the given value and return its “cleaned” value as an appropriate Python object. Raise ValidationError for any errors.

class service_objects.fields.ModelField(model_class, allow_unsaved=False, *args, **kwargs)

A field for Service that accepts an object of the specified Model:

class Person(models.Model):
    first_name = models.CharField(max_length=30)
    last_name = models.CharField(max_length=30)
    last_updated = models.DateTimeField()


class UpdatePerson(Service):
    person = ModelField(Person)

    process(self):
        person = self.cleaned_data['person']
        person.last_updated = now()
        person.save()


user = Person(first_name='John', last_name='Smith')
user.save()

UpdatePerson.execute({
    'person': user
})
Parameters:
  • model_class – Django Model or dotted string of : class:Model name
  • allow_unsaved – Whether the object is required to be saved to the database
clean(value)

Validate the given value and return its “cleaned” value as an appropriate Python object. Raise ValidationError for any errors.

class service_objects.fields.MultipleFormField(form_class, min_count=1, max_count=None, *args, **kwargs)

A field for Service that accepts a list of objects which is translated into multiple Form objects:

class PersonForm(forms.Form):
    name = forms.CharField()


class UpdateOrganizationService(Service):
    people = MultipleFormField(PersonForm)

    def process(self):
        people = self.cleaned_data['people']
        for person in people:
            print(person.cleaned_data['name'])

UpdateOrganizationService.execute({
    'people': [
        { 'name': 'John Smith' },
        { 'name': 'Adam Davis' },
    ]
})
clean(values)

Validate the given value and return its “cleaned” value as an appropriate Python object. Raise ValidationError for any errors.

class service_objects.fields.MultipleModelField(model_class, allow_unsaved=False, *args, **kwargs)

A multiple model version of ModelField, will check each passed in object to match the specified Model:

class Person(models.Model):
    first_name = models.CharField(max_length=30)
    last_name = models.CharField(max_length=30)


class AssociatePeople(Service):
    people = MultipleModelField(Person, allow_unsaved=True)


users = [
    Person(first_name='John', last_name='Smith'),
    Person(first_name='Jane', last_name='Smith')
]

AssociatePeople.execute({
    'people': users
})

for user in users:
    user.save()
Parameters:
  • model_class – Django Model or dotted string of : class:Model name
  • allow_unsaved – Whether the object is required to be saved to the database
clean(values)

Validate the given value and return its “cleaned” value as an appropriate Python object. Raise ValidationError for any errors.

Services module

class service_objects.services.Service(data=None, files=None, auto_id='id_%s', prefix=None, initial=None, error_class=<class 'django.forms.utils.ErrorList'>, label_suffix=None, empty_permitted=False, field_order=None, use_required_attribute=None, renderer=None)

Based on Django’s Form, designed to encapsulate Business Rules functionality. Input values are validated against the Service’s defined fields before calling main functionality:

class UpdateUserEmail(Service):
    user = ModelField(User)
    new_email = forms.EmailField()

    def process(self):
        old_email = user.email
        user.email = self.cleaned_data['new_email']
        user.save()

        send_email(
            'Email Update',
            'Your email was changed',
            'system',
            [old_email]
        )


user = User.objects.get(id=20)

UpdateUserEmail.execute({
    'user': user,
    'new_email': 'John.Smith@example.com'
})
Variables:
  • db_transaction (boolean) – controls if execute() is performed inside a Django database transaction. Default is True.
  • using (string) – In a multiple database setup, controls which database connection is used from the transaction. Defaults to DEFAULT_DB_ALIAS which works in a single database setup.
classmethod execute(inputs, files=None, **kwargs)

Function to be called from the outside to kick off the Service functionality.

Parameters:
  • inputs (dictionary) – data parameters for Service, checked against the fields defined on the Service class.
  • files (dictionary) – usually request’s FILES dictionary or None.
  • **kwargs (dictionary) –

    any additional parameters Service may need, can be an empty dictionary

post_process()

Post process method to be perform extra actions once process() successfully executes.

process()

Main method to be overridden; contains the Business Rules functionality.

service_clean()

Calls base Form’s is_valid() to verify inputs against Service’s fields and raises InvalidInputsError if necessary.

class service_objects.services.ModelService(data=None, files=None, auto_id='id_%s', prefix=None, initial=None, error_class=<class 'django.forms.utils.ErrorList'>, label_suffix=None, empty_permitted=False, field_order=None, use_required_attribute=None, renderer=None)

Same as Service but auto-creates fields based on the provided Model. Additionally, You can manually create fields to override or extend the auto-created fields:

class Person(models.Model):
    first_name = models.CharField(max_length=30)
    last_name = models.CharField(max_length=30)
    email = models.EmailField()


class CreatePersonService(Service):
    class Meta:
        model = Person
        fields = '_all_'

    notify = forms.BooleanField()

    def process(self):
        person = Person(
            first_name = self.cleaned_data['first_name'],
            last_name = self.cleaned_data['last_name'],
            email = self.cleaned_data['email']
        )
        person.save()

        if self.cleaned_data['notify']:
            django.send_mail(
                'Account Created',
                'An account has been created for you'
                'System',
                [person.email]
            )


CreatePersonService.execute({
    'first_name': 'John',
    'last_name': 'Smith',
    'notify': True
})

Views module

class service_objects.views.CreateServiceView(**kwargs)

Based on Django’s CreateView, designed to call the Service class if the form is valid.

class service_objects.views.ServiceView(**kwargs)

Based on Django’s FormView, designed to call a Service class if the Form is valid. If form_class is None, ServiceView will use service_class for the Form to present the UI to the User:

from django.core.urlresolvers import reverse_lazy

from service_objects.views import ServiceView

from .forms import BookingForm
from .services import CreateBookingService


class CreateBookingView(ServiceView):
    form_class = BookingForm
    service_class = CreateBookingService
    template_name = 'booking/create_booking.html'
    success_url = reverse_lazy('booking:success')
class service_objects.views.UpdateServiceView(**kwargs)

Based on Django’s UpdateView, designed to call the Service class if the form is valid.