Common utilities used in ARC Django projects
Project description
# ARCUtils
[![Build Status](https://travis-ci.org/PSU-OIT-ARC/django-arcutils.svg?branch=master)](https://travis-ci.org/PSU-OIT-ARC/django-arcutils)
This package provides utilities that are commonly needed in ARC Django projects. It supports Python
3.3+ and Django 1.8+.
## General Note
If ARCUtils contains a specific type of functionality that is needed in an ARC project, it is
generally preferable to use the ARCUtils functionality instead of another package, since the entire
purpose of ARCUtils is to encapsulate the configuration and functionality needed by many or most
ARC projects.
On the other hand (and this is a note to self as much as to anyone else), we should _avoid_ adding
functionality to ARCUtils whenever possible.
## Development
To work on this package, run `make init`; this will create a virtualenv for you, install the
package in editable mode, and run the tests. Take a look at the Makefile to see the actual commands
that are run.
## Testing
Run `make test`.
## Usage
_The following assumes your package has a setup.py that uses setuptools' `setup()` and that you are
using pip. You will need to specify `--find-links http://cdn.research.pdx.edu/pypi/dist/` when
running `pip install` (it's easiest to add `--find-links ...` to the top of the project's
requirements.txt)._
To use this package in a Django project, do the following:
- Add `'django-arcutils'` to `install_requires` in setup.py
- To use the LDAP features, add `'django-arcutils[ldap]'` to `install_requires`
- To use template tags, add `'arcutils'` to `INSTALLED_APPS`
## Features
NOTE: Many features have not been documented yet :( To get an idea of all the available features,
take a look at the modules and packages in the top level `arcutils` directory.
### Console Script
Some ARCUtils functionality can be accessed via the `arcutils` console script (or via
`python -m arcutils`). Currently, there is one subcommand for running LDAP queries:
arcutils ldap '(uid=pants)'
### CAS - arcutils.cas
CAS is used when a project needs to log users in with their PSU accounts. The basic setup is
straightforward:
- Add `"arcutils.cas.backends.CASModelBackend"` to the project's `AUTHENTICATION_BACKENDS` (in most
cases, this will be the only value in `AUTHENTICATION_BACKENDS`)
- Include CAS URLs in the project's root URLconf: `url(r'^account/', include(arcutils.cas.urls))`
By default, the first time a user logs in, a `User` record (with no password) will be created in the
project's database.
### Database - arcutils.db
- `ChoiceEnum`
class FooType(ChoiceEnum):
A = 1
B = 2
class SomeModel(models.Model):
foo = models.ChoiceField(choices=FooType.as_choices())
- `will_be_deleted_with(obj)` returns 2-tuples of
`(model class of objects in set, set of objects that will be deleted along with obj)`. This can
be used in delete views to list the objects that will be deleted in a cascading manner.
- `arcutils.db.dictfetchall`: pass a cursor and get the rows back as a dict
### Forms - arcutils.forms
- `arcutils.forms.BaseFormSet` and `arcutils.forms.BaseModelFormSet` have an
`iter_with_empty_form_first()` method that is is basically
`([formset.empty_form] + formset.forms)`. This makes it convenient to iterate over the empty form
in templates without having a special case for it.
- `arcutils.forms.BaseFormSet` and `arcutils.forms.BaseModelFormSet` override the `clean` method
so that if a form is being deleted, its validation errors are blanked out.
### LDAP - arcutils.ldap
To use the LDAP features, you will need at least a minimal set of LDAP settings:
LDAP = {
'default': {
'host': 'ldap://ldap-bulk.oit.pdx.edu',
'search_base': 'ou=people,dc=pdx,dc=edu',
}
}
- `arcutils.ldap.ldapsearch(query, using='default', **kwargs)` performs an LDAP search using the
LDAP connection specified by the using parameter. By default, each LDAP result is parsed into
a "profile", which is just a dict with user info pulled from the LDAP attributes:
results = ldapsearch('(uid=mdj2)')
print(results[0]) # -> {'first_name': 'Matt', 'last_name': 'Johnson', ...}
### Settings - arcutils.settings
TODO: Write this section.
### Tasks - arcutils.tasks
Implements a simple daily task runner as an alternative to cron or Celery.
[![Build Status](https://travis-ci.org/PSU-OIT-ARC/django-arcutils.svg?branch=master)](https://travis-ci.org/PSU-OIT-ARC/django-arcutils)
This package provides utilities that are commonly needed in ARC Django projects. It supports Python
3.3+ and Django 1.8+.
## General Note
If ARCUtils contains a specific type of functionality that is needed in an ARC project, it is
generally preferable to use the ARCUtils functionality instead of another package, since the entire
purpose of ARCUtils is to encapsulate the configuration and functionality needed by many or most
ARC projects.
On the other hand (and this is a note to self as much as to anyone else), we should _avoid_ adding
functionality to ARCUtils whenever possible.
## Development
To work on this package, run `make init`; this will create a virtualenv for you, install the
package in editable mode, and run the tests. Take a look at the Makefile to see the actual commands
that are run.
## Testing
Run `make test`.
## Usage
_The following assumes your package has a setup.py that uses setuptools' `setup()` and that you are
using pip. You will need to specify `--find-links http://cdn.research.pdx.edu/pypi/dist/` when
running `pip install` (it's easiest to add `--find-links ...` to the top of the project's
requirements.txt)._
To use this package in a Django project, do the following:
- Add `'django-arcutils'` to `install_requires` in setup.py
- To use the LDAP features, add `'django-arcutils[ldap]'` to `install_requires`
- To use template tags, add `'arcutils'` to `INSTALLED_APPS`
## Features
NOTE: Many features have not been documented yet :( To get an idea of all the available features,
take a look at the modules and packages in the top level `arcutils` directory.
### Console Script
Some ARCUtils functionality can be accessed via the `arcutils` console script (or via
`python -m arcutils`). Currently, there is one subcommand for running LDAP queries:
arcutils ldap '(uid=pants)'
### CAS - arcutils.cas
CAS is used when a project needs to log users in with their PSU accounts. The basic setup is
straightforward:
- Add `"arcutils.cas.backends.CASModelBackend"` to the project's `AUTHENTICATION_BACKENDS` (in most
cases, this will be the only value in `AUTHENTICATION_BACKENDS`)
- Include CAS URLs in the project's root URLconf: `url(r'^account/', include(arcutils.cas.urls))`
By default, the first time a user logs in, a `User` record (with no password) will be created in the
project's database.
### Database - arcutils.db
- `ChoiceEnum`
class FooType(ChoiceEnum):
A = 1
B = 2
class SomeModel(models.Model):
foo = models.ChoiceField(choices=FooType.as_choices())
- `will_be_deleted_with(obj)` returns 2-tuples of
`(model class of objects in set, set of objects that will be deleted along with obj)`. This can
be used in delete views to list the objects that will be deleted in a cascading manner.
- `arcutils.db.dictfetchall`: pass a cursor and get the rows back as a dict
### Forms - arcutils.forms
- `arcutils.forms.BaseFormSet` and `arcutils.forms.BaseModelFormSet` have an
`iter_with_empty_form_first()` method that is is basically
`([formset.empty_form] + formset.forms)`. This makes it convenient to iterate over the empty form
in templates without having a special case for it.
- `arcutils.forms.BaseFormSet` and `arcutils.forms.BaseModelFormSet` override the `clean` method
so that if a form is being deleted, its validation errors are blanked out.
### LDAP - arcutils.ldap
To use the LDAP features, you will need at least a minimal set of LDAP settings:
LDAP = {
'default': {
'host': 'ldap://ldap-bulk.oit.pdx.edu',
'search_base': 'ou=people,dc=pdx,dc=edu',
}
}
- `arcutils.ldap.ldapsearch(query, using='default', **kwargs)` performs an LDAP search using the
LDAP connection specified by the using parameter. By default, each LDAP result is parsed into
a "profile", which is just a dict with user info pulled from the LDAP attributes:
results = ldapsearch('(uid=mdj2)')
print(results[0]) # -> {'first_name': 'Matt', 'last_name': 'Johnson', ...}
### Settings - arcutils.settings
TODO: Write this section.
### Tasks - arcutils.tasks
Implements a simple daily task runner as an alternative to cron or Celery.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
django-arcutils-2.16.0.tar.gz
(69.1 kB
view hashes)