# Banjo
Banjo is an abstraction over django which provides a simplified subset of django's
functionality, meant for beginners. All the django documentation can be used for
reference, and many django patterns are replicated here.
## Needs
The purpose of Banjo is to introduce databases as a persistence layer behind an
API server, while abstracting away details for which students are not yet ready
and creating as few misconceptions as possible.
Banjo should be thought of as scaffolding; when they are ready, students should
be able to seamlessly transition to django.
Specific concepts which we target for simplification include:
- Simplify DB schema: A severely-limited subset of field types is provided.
Field names correspond to familiar Python types. All fields have default values.
Migrations are handled automatically. Within these constraints, django's full
ORM is available.
- Simplify filesystem layout: Only two files are required: `models.py` and
`views.py`.
- Simplify management commands: There is a single command, `banjo`, which
effectively runs django's `makemigrations`, `migrate`, and `runserver` in sequence.
`banjo --shell` enters the REPL with all user-defined models loaded.
- Simplify request/response lifecycle: View functions receive a dict of params and
must return a dict. View-URL binding is handled by decorators, as in flask, and all
URLs are static (there are no placeholders and no params are passed to the
view). Http errors are provided as exceptions, which simplifies control flow.
Models have `from_dict` (class method) and `to_dict` (instance method) helpers.
Banjo was designed for use by teachers familiar with django; this is intentionally a
leaky abstraction which provides a structured introduction into the power and
the complexity of the underlying system.
## Creating an app
Banjo can be installed with `pip install django-banjo`.
To write a Banjo app, create a folder called `app`, define models in `models.py` and
define views in `views.py`. Here's a simple example.
### Models
First, we define our models. Banjo provides five field types:
- `BooleanField` (`True`, `False`)
- `IntegerField` (`1`, `-102`)
- `FloatField` (`0.045`, `11.5`)
- `StringField` (`"alligator"`, `"hazelnut"`)
- `ForeignKey` (An instance of another model)
Create a Model for each object your app will interact with.
# app/models.py
from banjo.models import Model, StringField
class Animal(Model):
name = StringField()
sound = StringField()
### Views
Next we define our views. Each view is a function which receives a dict (called
`params` in the example below) and which must return a dict. Use the
`banjo.urls.route_get` and `banjo.urls.route_post` decorators to route URLs to
your view functions.
# app/views.py
from banjo.urls import route_get, route_post
from app.models import Animal
@route_post('newanimal', args={'name': str, 'sound': str})
def add_animal(params):
animal = Animal.from_dict(params)
animal.save()
return animal.to_dict()
@route_get('listen')
def list_animal_sounds(params):
sounds = []
for animal in Animal.objects.all():
sounds.append('{} says {}'.format(animal.name, animal.sound))
return {'sounds': sounds}
Some views, such as "newanimal," require arguments. When a view requires arguments,
pass an `args` dict to the decorator to specify the expected names and types of arguments.
Argument types must be `str`, `bool`, `int`, or `float`.
### HTTP errors
If something goes wrong and it's the client's fault, you can raise an error.
For example, you might add another view to `app/views.py`:
from banjo.http import Forbidden
@route_get('secrets')
def do_not_show_the_secrets(params):
raise Forbidden("Nice try.")
Again, from the command line:
$ http GET localhost:5000/secrets
HTTP/1.1 403 Forbidden
{
"error": "Nice try."
}
The following errors are available in `banjo.http`:
- `BadRequest` (400)
- `Forbidden` (403)
- `NotFound` (404)
- `NotAllowed` (405)
- `ImATeapot` (418)
## Running the app
Now you can run `banjo` from the directory containing the `app` folder and the server
will start. Use the `--port` command to serve from a custom port; the default is
5000.
Banjo provides a visual API browser at `/api`.
Here is an example of interacting with this app using the `httpie` command-line
utility:
$ http localhost:5000/newanimal name=elehpant sound=pffffftttttt
{
"id": 1,
"name": "elephant",
"sound": "pffffftttttt"
}
$ http localhost:5000/newanimal name=squirrel sound=chcheee
{
"id": 2,
"name": "squirrel",
"sound": "chcheee"
}
$ http localhost:5000/listen
{
"sounds": [
"elephant says pffffftttttt",
"squirrel says chcheee"
]
}
## Shell
You can also interact with your app's models from a Python shell. Just pass the
`--shell` argument to banjo:
$ banjo --shell
> Animal.objects.count()
2
Raw data
{
"_id": null,
"home_page": "https://github.com/cproctor/django-banjo",
"name": "django-banjo",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Chris Proctor",
"author_email": "chris@chrisproctor.net",
"download_url": "https://files.pythonhosted.org/packages/71/1f/04dcdcaae6d51f1fb7f89880666f19ba4a47aeb9d973b730dd095dbd21a1/django_banjo-0.7.3.tar.gz",
"platform": null,
"description": "# Banjo\n\nBanjo is an abstraction over django which provides a simplified subset of django's\nfunctionality, meant for beginners. All the django documentation can be used for\nreference, and many django patterns are replicated here.\n\n## Needs\n\nThe purpose of Banjo is to introduce databases as a persistence layer behind an\nAPI server, while abstracting away details for which students are not yet ready \nand creating as few misconceptions as possible. \nBanjo should be thought of as scaffolding; when they are ready, students should\nbe able to seamlessly transition to django.\n\nSpecific concepts which we target for simplification include:\n\n- Simplify DB schema: A severely-limited subset of field types is provided.\n Field names correspond to familiar Python types. All fields have default values. \n Migrations are handled automatically. Within these constraints, django's full \n ORM is available.\n- Simplify filesystem layout: Only two files are required: `models.py` and\n `views.py`. \n- Simplify management commands: There is a single command, `banjo`, which\n effectively runs django's `makemigrations`, `migrate`, and `runserver` in sequence.\n `banjo --shell` enters the REPL with all user-defined models loaded.\n- Simplify request/response lifecycle: View functions receive a dict of params and \n must return a dict. View-URL binding is handled by decorators, as in flask, and all\n URLs are static (there are no placeholders and no params are passed to the\n view). Http errors are provided as exceptions, which simplifies control flow. \n Models have `from_dict` (class method) and `to_dict` (instance method) helpers.\n\nBanjo was designed for use by teachers familiar with django; this is intentionally a \nleaky abstraction which provides a structured introduction into the power and \nthe complexity of the underlying system. \n\n## Creating an app\n\nBanjo can be installed with `pip install django-banjo`.\n\nTo write a Banjo app, create a folder called `app`, define models in `models.py` and \ndefine views in `views.py`. Here's a simple example. \n\n### Models\n\nFirst, we define our models. Banjo provides five field types:\n\n- `BooleanField` (`True`, `False`)\n- `IntegerField` (`1`, `-102`)\n- `FloatField` (`0.045`, `11.5`)\n- `StringField` (`\"alligator\"`, `\"hazelnut\"`)\n- `ForeignKey` (An instance of another model)\n\nCreate a Model for each object your app will interact with.\n\n # app/models.py\n from banjo.models import Model, StringField\n\n class Animal(Model):\n name = StringField()\n sound = StringField()\n\n### Views\n\nNext we define our views. Each view is a function which receives a dict (called\n`params` in the example below) and which must return a dict. Use the \n`banjo.urls.route_get` and `banjo.urls.route_post` decorators to route URLs to\nyour view functions. \n \n # app/views.py\n from banjo.urls import route_get, route_post\n from app.models import Animal\n \n @route_post('newanimal', args={'name': str, 'sound': str})\n def add_animal(params):\n animal = Animal.from_dict(params)\n animal.save()\n return animal.to_dict()\n\n @route_get('listen')\n def list_animal_sounds(params):\n sounds = []\n for animal in Animal.objects.all():\n sounds.append('{} says {}'.format(animal.name, animal.sound)) \n return {'sounds': sounds}\n\nSome views, such as \"newanimal,\" require arguments. When a view requires arguments, \npass an `args` dict to the decorator to specify the expected names and types of arguments.\nArgument types must be `str`, `bool`, `int`, or `float`.\n\n### HTTP errors\n\nIf something goes wrong and it's the client's fault, you can raise an error.\nFor example, you might add another view to `app/views.py`:\n\n from banjo.http import Forbidden\n\n @route_get('secrets')\n def do_not_show_the_secrets(params):\n raise Forbidden(\"Nice try.\")\n\nAgain, from the command line:\n\n $ http GET localhost:5000/secrets\n HTTP/1.1 403 Forbidden\n \n {\n \"error\": \"Nice try.\"\n }\n\n\nThe following errors are available in `banjo.http`:\n\n- `BadRequest` (400)\n- `Forbidden` (403)\n- `NotFound` (404)\n- `NotAllowed` (405)\n- `ImATeapot` (418)\n\n## Running the app\n\nNow you can run `banjo` from the directory containing the `app` folder and the server\nwill start. Use the `--port` command to serve from a custom port; the default is\n5000.\n\nBanjo provides a visual API browser at `/api`. \n\n\n\nHere is an example of interacting with this app using the `httpie` command-line\nutility:\n\n $ http localhost:5000/newanimal name=elehpant sound=pffffftttttt\n\n { \n \"id\": 1,\n \"name\": \"elephant\",\n \"sound\": \"pffffftttttt\"\n }\n\n $ http localhost:5000/newanimal name=squirrel sound=chcheee\n\n { \n \"id\": 2,\n \"name\": \"squirrel\",\n \"sound\": \"chcheee\"\n }\n\n $ http localhost:5000/listen\n\n {\n \"sounds\": [\n \"elephant says pffffftttttt\",\n \"squirrel says chcheee\"\n ]\n }\n\n\n## Shell\n\nYou can also interact with your app's models from a Python shell. Just pass the\n`--shell` argument to banjo:\n\n $ banjo --shell\n > Animal.objects.count()\n 2\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simplified abstraction over django for beginners.",
"version": "0.7.3",
"project_urls": {
"Documentation": "https://django-banjo.readthedocs.io",
"Homepage": "https://github.com/cproctor/django-banjo",
"Repository": "https://github.com/cproctor/django-banjo"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "48a58d0c0849af2ff2aca6df31425ce90731808e037e56e8d06cdb4e1f73e030",
"md5": "64dae2214886a6cca846616a666c9e4e",
"sha256": "fbb4f5f3f0f9ad55e6804476b4ab59337c57591430f0c12f4365cb737bb93811"
},
"downloads": -1,
"filename": "django_banjo-0.7.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "64dae2214886a6cca846616a666c9e4e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 13844,
"upload_time": "2024-08-29T11:27:03",
"upload_time_iso_8601": "2024-08-29T11:27:03.858134Z",
"url": "https://files.pythonhosted.org/packages/48/a5/8d0c0849af2ff2aca6df31425ce90731808e037e56e8d06cdb4e1f73e030/django_banjo-0.7.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "711f04dcdcaae6d51f1fb7f89880666f19ba4a47aeb9d973b730dd095dbd21a1",
"md5": "162d70061619d788127ffaf3b4c87ebf",
"sha256": "016f8e218915308e1293d036abf0301e7f078f4cc1ff5d3a2dd04c7bc5d6cfa1"
},
"downloads": -1,
"filename": "django_banjo-0.7.3.tar.gz",
"has_sig": false,
"md5_digest": "162d70061619d788127ffaf3b4c87ebf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 12172,
"upload_time": "2024-08-29T11:27:05",
"upload_time_iso_8601": "2024-08-29T11:27:05.195550Z",
"url": "https://files.pythonhosted.org/packages/71/1f/04dcdcaae6d51f1fb7f89880666f19ba4a47aeb9d973b730dd095dbd21a1/django_banjo-0.7.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-29 11:27:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cproctor",
"github_project": "django-banjo",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "django-banjo"
}
JSON
