EULcommon¶

auth - Customized permission decorators¶

Customized decorators that enhance the default behavior of django.contrib.auth.decorators.permission_required().

The default behavior of django.contrib.auth.decorators.permission_required() for any user does not meet the required permission level is to redirect them to the login page– even if that user is already logged in. For more discussion of this behavior and current status in Django, see: http://code.djangoproject.com/ticket/4617

These decorators work the same way as the Django equivalents, with the added feature that if the user is already logged in and does not have the required permission, they will see 403 page instead of the login page.

The decorators should be used exactly the same as their django equivalents.

The code is based on the django snippet code at http://djangosnippets.org/snippets/254/

auth.user_passes_test_with_403(test_func, login_url=None)¶

View decorator that checks to see if the user passes the specified test. See django.contrib.auth.decorators.user_passes_test().

Anonymous users will be redirected to login_url, while logged in users that fail the test will be given a 403 error. In the case of a 403, the function will render the 403.html template.

auth.permission_required_with_403(perm, login_url=None)¶

Decorator for views that checks whether a user has a particular permission enabled, redirecting to the login page or rendering a 403 as necessary.

See django.contrib.auth.decorators.permission_required().

auth.user_passes_test_with_ajax(test_func, login_url=None, redirect_field_name='next')¶

Decorator for views that checks that the user passes the given test, redirecting to the log-in page if necessary. The test should be a callable that takes the user object and returns True if the user passes.

Returns special response to ajax calls instead of blindly redirecting.

To use with class methods instead of functions, use django.utils.decorators.method_decorator(). See http://docs.djangoproject.com/en/dev/releases/1.2/#user-passes-test-login-required-and-permission-required

Usage is the same as django.contrib.auth.decorators.user_passes_test():

@user_passes_test_with_ajax(lambda u: u.has_perm('polls.can_vote'), login_url='/loginpage/')
def my_view(request):
    ...

auth.login_required_with_ajax(function=None, redirect_field_name='next')¶

Decorator for views that checks that the user is logged in, redirecting to the log-in page if necessary, but returns a special response for ajax requests. See eulcommon.djangoextras.auth.decorators.user_passes_test_with_ajax().

Example usage:

@login_required_with_ajax()
def my_view(request):
    ...

auth.permission_required_with_ajax(perm, login_url=None)¶

Decorator for views that checks whether a user has a particular permission enabled, redirecting to the log-in page if necessary, but returns a special response for ajax requests. See eulcore.django.auth.decorators.user_passes_test_with_ajax().

Usage is the same as django.contrib.auth.decorators.permission_required()

@permission_required_with_ajax('polls.can_vote', login_url='/loginpage/')
def my_view(request):
    ...

http - Content Negotiation for Django views¶

http.content_negotiation(formats, default_type='text/html')¶

Provides basic content negotiation and returns a view method based on the best match of content types as indicated in formats.

Parameters:	formats – dictionary of content types and corresponding methods default_type – string the decorated method is the return type for.

Example usage:

def rdf_view(request, arg):
    return RDF_RESPONSE

@content_negotiation({'application/rdf+xml': rdf_view})
def html_view(request, arg):
    return HTML_RESPONSE

The above example would return the rdf_view on a request type of application/rdf+xml and the normal view for anything else.

Any django.http.HttpResponse returned by the view method chosen by content negotiation will have a ‘Vary: Accept’ HTTP header added.

NOTE: Some web browsers do content negotiation poorly, requesting application/xml when what they really want is application/xhtml+xml or text/html. When this type of Accept request is detected, the default type will be returned rather than the best match that would be determined by parsing the Accept string properly (since in some cases the best match is application/xml, which could return non-html content inappropriate for display in a web browser).

BinaryStructure Subclasses¶

General Usage¶

Suppose we have an 8-byte file whose binary data consists of the bytes 0, 1, 2, 3, etc.:

>>> with open('numbers.bin') as f:
...     f.read()
...
'\x00\x01\x02\x03\x04\x05\x06\x07'

Suppose further that these contents represent sensible binary data, laid out such that the first two bytes are a literal string value. Except that sometimes, in the binary format we’re parsing, it might sometimes be necessary to interpret those first two bytes not as a literal string, but instead as a number, encoded as a big-endian unsigned integer. Following that is a variable-length string, encoded with the total string length in the third byte.

This structure might be represented as:

from eulcommon.binfile import *
class MyObject(BinaryStructure):
    mybytes = ByteField(0, 2)
    myint = IntegerField(0, 2)
    mystring = LengthPrepededStringField(2)

Client code might then read data from that file:

>>> f = open('numbers.bin')
>>> obj = MyObject(f)
>>> obj.mybytes
'\x00\x01'
>>> obj.myint
1
>>> obj.mystring
'\x03\x04'

It’s not uncommon for such binary structures to be repeated at different points within a file. Consider if we overlay the same structure on the same file, but starting at byte 1 instead of byte 0:

>>> f = open('numbers.bin')
>>> obj = MyObject(f, offset=1)
>>> obj.mybytes
'\x01\x02'
>>> obj.myint
258
>>> obj.mystring
'\x04\x05\x06'

BinaryStructure¶

class eulcommon.binfile.BinaryStructure(fobj=None, mm=None, offset=0)¶

A superclass for binary data structures superimposed over files.

Typical users will create a subclass containing field objects (e.g., ByteField, IntegerField). Each subclass instance is created with a file and with an optional offset into that file. When code accesses fields on the instance, they are calculated from the underlying binary file data.

Instead of a file, it is occasionally appropriate to overlay an mmap structure (from the mmap standard library). This happens most often when one BinaryStructure instance creates another, passing self.mmap to the secondary object’s constructor. In this case, the caller may specify the mm argument instead of an fobj.

Parameters:	fobj – a file object or filename to overlay mm – a mmap object to overlay offset – the offset into the file where the structured data begins

Field classes¶

class eulcommon.binfile.ByteField(start, end)¶

A field mapping fixed-length binary data to Python strings.

Parameters:	start – The offset into the structure of the beginning of the byte data. end – The offset into the structure of the end of the byte data. This is actually one past the last byte of data, so a four-byte ByteField starting at index 4 would be defined as ByteField(4, 8) and would include bytes 4, 5, 6, and 7 of the binary structure.

Typical users will create a ByteField inside a BinaryStructure subclass definition:

class MyObject(BinaryStructure):
    myfield = ByteField(0, 4) # the first 4 bytes of the file

When you instantiate the subclass and access the field, its value will be the literal bytes at that location in the structure:

>>> o = MyObject('file.bin')
>>> o.myfield
'ABCD'

class eulcommon.binfile.LengthPrependedStringField(offset)¶

A field mapping variable-length binary strings to Python strings.

This field accesses strings encoded with their length in their first byte and string data following that byte.

Parameters:	offset – The offset of the single-byte string length.

Typical users will create a LengthPrependedStringField inside a BinaryStructure subclass definition:

class MyObject(BinaryStructure):
    myfield = LengthPrependedStringField(0)

When you instantiate the subclass and access the field, its length will be read from that location in the structure, and its data will be the bytes immediately following it. So with a file whose first bytes are '\x04ABCD':

>>> o = MyObject('file.bin')
>>> o.myfield
'ABCD'

class eulcommon.binfile.IntegerField(start, end)¶

A field mapping fixed-length binary data to Python numbers.

This field accessses arbitrary-length integers encoded as binary data. Currently only big-endian, unsigned integers are supported.

Parameters:	start – The offset into the structure of the beginning of the byte data. end – The offset into the structure of the end of the byte data. This is actually one past the last byte of data, so a four-byte IntegerField starting at index 4 would be defined as IntegerField(4, 8) and would include bytes 4, 5, 6, and 7 of the binary structure.

Typical users will create an IntegerField inside a BinaryStructure subclass definition:

class MyObject(BinaryStructure):
    myfield = IntegerField(3, 6) # integer encoded in bytes 3, 4, 5

When you instantiate the subclass and access the field, its value will be big-endian unsigned integer encoded at that location in the structure. So with a file whose bytes 3, 4, and 5 are '\x00\x01\x04':

>>> o = MyObject('file.bin')
>>> o.myfield
260

0.18¶

• Custom auth decorators in eulcommon.djangoextras.auth.decorators now have the capacity to take additional view parameters, with fallback to old behavior for compatibility

0.17.0¶

• searchutil can now parse field:value pairs in search term strings. See parse_search_terms(). The existing search term parsing method, search_terms(), should continue to work as before.
• eulcommon.binfile has been moved into the new bodatools; it will remain in eulcommon for the upcoming release as deprecated, and then be removed at a later date.

0.16.2 - template hotfix redux¶

• Add missing pagination template to setup.py install

0.16.1 - template hotfix¶

• Add missing pagination template to sdist

0.16.0¶

• Parsing for quotable search strings
• Utility to limit pagination display to nearby pages

0.15.0 - Initial Release¶

• Split out and re-organized common, useful components (binfile, djangoextras) from eulcore into eulcommon for easier re-use.