Skip to content

Commit c33c46a

Browse files
sect2ksect2k
committed
Initial release on PyPI (version 1.9.0)
0 parents  commit c33c46a

17 files changed

+902
-0
lines changed

‎.gitignore

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
.DS_Store
2+
*.pyc

‎.vscode/settings.json

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"python.linting.pylintEnabled": false
3+
}

‎LICENSE

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
The MIT License
2+
3+
Copyright (c) 2017 Mitja Pagon, Inueni Ltd.
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in
13+
all copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21+
THE SOFTWARE.

‎MANIFEST.in

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
include README.md
2+
include LICENSE
3+
recursive-include subadmin/templates *
4+
global-exclude __pycache__
5+
global-exclude *.py[co]

‎README.md

+89
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# django-subadmin
2+
3+
`django-subadmin` provides a special kind of `ModelAdmin`, called `SubAdmin`, that allows it to be nested within another `ModelAdmin` instance. Similar to django's built-in `InlineModelAdmin`, it allows editing of related objects, but instead of doing it inline, it gives you a full `ModelAdmin` as sub-admin of parent `ModelAdmin`. Like `InlineModelAdmin` it works on models related by `ForeignKey`. Multiple `SubAdmin` instances can be nested within a single `ModelAdmin` or `SubAdmin` allowing for multi-level nesting.
4+
5+
## Installation
6+
7+
The easiest and recommended way to install `django-subadmin` is from [PyPI](https://pypi.python.org/pypi/django-subadmin)
8+
9+
```
10+
pip install django-subadmin
11+
```
12+
13+
You need to add `subadmin` to `INSTALLED_APPS` in your projects `settings.py`, otherwise `django` will not be able to find the necessary templates and template tags.
14+
15+
```
16+
# settings.py
17+
18+
INSTALLED_APPS = (
19+
...
20+
'subadmin',
21+
...
22+
)
23+
```
24+
25+
## Example Usage
26+
27+
Sometimes things are best explained by an example. Let's say you have two related models.
28+
29+
```python
30+
# models.py
31+
32+
class MailingList(models.Model):
33+
name = models.CharField(max_length=100)
34+
35+
36+
class Subscriber(models.Model):
37+
mailing_list = models.ForeignKey(MailingList)
38+
username = models.CharField(max_length=100)
39+
```
40+
41+
If you wish to display only subscribers belonging to a particular mailing list in django admin, your only options is to use `InlineModelAdmin`, which is not very practical when dealing with large number of related objects, plus, you loose all the cool functionality of `ModelAdmin` like searching, filtering, pagination, etc ...
42+
43+
This is where `SubAdmin` comes in.
44+
45+
```python
46+
# admin.py
47+
48+
from subadmin import SubAdmin, RootSubAdmin
49+
from .models import MailingList, Subscriber
50+
51+
# Instead of admin.ModelAdmin we subclass SubAdmin,
52+
# we also set model attribute
53+
54+
class SubscriberSubAdmin(SubAdmin):
55+
model = Subscriber
56+
list_display = ('username',)
57+
58+
59+
# Since this is the top level model admin, which will be registred with admin.site,
60+
# we subclass RootSubAdmin and set subadmins attribute
61+
62+
class MailingListAdmin(RootSubAdmin):
63+
list_display = ('name',)
64+
65+
subadmins = [SubscriberSubAdmin]
66+
67+
68+
admin.site.register(MailingList, MailingListAdmin)
69+
```
70+
71+
With just a few lines of code you get a fully functional `ModelAdmin`, that will automatically pull in just the relevant related objects, based on `ForeignKey` relation between the two models, it will also auto set `ForeignKey` fields for nested relations and exclude them from change form when adding and editing objects on subadmin.
72+
73+
If you want to see it in action, or get a more in-depth look at how to set everything up, check out <https://github.com/inueni/django-subadmin-example>.
74+
75+
76+
## Supported Django versions
77+
78+
Current release of `django-subadmin` is **1.9.0** and is compatible with Django 1.9, 1.10 and 1.11.
79+
80+
Since Django versions before 1.11 don't support `get_exclude` on `ModelAdmin` instances, a workaround that temporarily stores excluded fields on `ModelAdmin` instance, is used. This should not cause any issues under normal circumstances.
81+
82+
#### Verison numbering
83+
84+
`django-subadmin` version numbers are related to Django version numbers. `django-subadmin` major and minor version numbers equal the minimal compatible django release.
85+
86+
87+
## Stability
88+
89+
`django-subadmin` has evolved from code that has been running on production servers since early 2014 without any issues. Still, the code has been heavily refactored prior to public release, and while it is unlikely to eat your data, consider it **BETA** software.

‎setup.py

+65
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
#!/usr/bin/env python
2+
# -*- coding: utf-8 -*-
3+
from __future__ import unicode_literals, print_function
4+
5+
from setuptools import setup, find_packages
6+
import os
7+
import sys
8+
9+
version = '1.9.0'
10+
11+
try:
12+
from pypandoc import convert
13+
def read_md(f):
14+
return convert(f, 'rst')
15+
except ImportError:
16+
print("warning: pypandoc module not found, could not convert Markdown to RST")
17+
def read_md(f):
18+
return open(f, 'r', encoding='utf-8').read()
19+
20+
21+
if sys.argv[-1] == 'publish':
22+
try:
23+
import pypandoc
24+
except ImportError:
25+
print("pypandoc not installed.\nUse `pip install pypandoc`.")
26+
27+
print("You probably want to also tag the version now:")
28+
print(" git tag -a %s -m 'version %s'" % (version, version))
29+
print(" git push --tags")
30+
sys.exit()
31+
32+
setup(
33+
name = 'django-subadmin',
34+
version = version,
35+
install_requires = (),
36+
author = 'Mitja Pagon',
37+
author_email = '[email protected]',
38+
license = 'MIT',
39+
url = 'https://github.com/inueni/django-subadmin/',
40+
keywords = 'django admin modeladmin foreignkey related field',
41+
description = 'A special kind of ModelAdmin that allows it to be nested within another ModelAdmin',
42+
long_description = read_md('README.md'),
43+
packages = find_packages(),
44+
include_package_data=True,
45+
zip_safe=False,
46+
classifiers=(
47+
'Development Status :: 4 - Beta',
48+
'Environment :: Web Environment',
49+
'Intended Audience :: Developers',
50+
'Operating System :: OS Independent',
51+
'License :: OSI Approved :: MIT License',
52+
'Topic :: Software Development :: Libraries :: Python Modules',
53+
'Programming Language :: Python',
54+
"Programming Language :: Python :: 2",
55+
'Programming Language :: Python :: 2.7',
56+
'Programming Language :: Python :: 3',
57+
'Programming Language :: Python :: 3.4',
58+
'Programming Language :: Python :: 3.5',
59+
'Programming Language :: Python :: 3.6',
60+
'Framework :: Django',
61+
'Framework :: Django :: 1.9',
62+
'Framework :: Django :: 1.10',
63+
'Framework :: Django :: 1.11',
64+
)
65+
)

0 commit comments

Comments
 (0)