`_ (required) *Used to generate thumbnails.*
- `pymongo `_ (optional) *Used for the Mongo DB backend.*
|development|
Utilities and backends for file storage.
See https://docs.djangoproject.com/en/stable/ref/files/storage/
.. warning::
Many of the resources in this package operate in a destructive manner; creating, removing, and updating files.
Setup
-----
To use the overwrite storage as the default, add the following to your ``settings.py`` file:
.. code-block:: python
# https://docs.djangoproject.com/en/stable/ref/settings/#default-file-storage
DEFAULT_FILE_STORAGE = "superdjango.storage.backends.OverwriteStorage"
.. _core-utils:
Utilities
=========
|development| |library|
**Version:** 0.16.0-d
General utilities not necessarily related to Django but nevertheless use for general operation.
Developer Reference: :ref:`core-utils-developer`
**Provides**
- Constants
- Utilities
**Dependencies**
- `beautifulsoup4 `_ (required) *Used to strip HTML tags.*
Boolean Operations
------------------
is_bool
.......
Determine if a given value is a boolean at run time.
.. code-block:: python
from superdjango.utils import is_bool
print(is_bool("yes"))
print(is_bool(True))
print(is_bool("No"))
print(is_bool(False))
.. tip::
By default, a liberal number of values are used to test. If you *just* want ``True`` or ``False``, simply pass
``(True, False)`` as ``test_values``.
to_bool
.......
Convert a given value to it's boolean equivalent.
.. code-block:: python
from superdjango.utils import to_bool
print(to_bool("yes"))
print(to_bool(1))
print(to_bool("no"))
print(to_bool(0))
Note that an unrecognized value will raise a value error.
.. code-block:: python
from superdjango.utils import to_bool
value = "not a boolean"
try:
print(to_bool(value))
except ValueError:
print('"%s" is not a boolean value.' % value)
File Operations
---------------
copy_file
.........
Copy a file from one location to another.
.. code-block:: python
from superdjango.utils import copy_file
copy_file("readme-template.txt", "path/to/project/readme.txt")
copy_tree
.........
Recursively copy a source directory to a given destination.
.. code-block:: python
from superdjango.utils import copy_tree
success = copy_tree("from/path", "to/path")
print(success)
read_csv
........
Read the contents of a CSV file.
.. code-block:: text
menu,identifier,sort_order,text,url
main,product,10,Product,/product/
main,solutions,20,Solutions,/solutions/
main,resources,30,Resources,/resources/
main,support,40,Support,https://support.example.com
main,about,50,About,/about/
main,contact,60,Contact,/contact/
.. code-block:: python
from superdjango.utils import read_csv
rows = read_csv("path/to/menus.csv", first_row_fields_names=True)
for r in rows:
print("%s: %s" % (row['identifier'], row['url']
read_file
.........
Read a file and return its contents.
.. code-block:: python
from superdjango.utils import read_file
output = read_file("path/to/readme.txt")
print(output)
write_file
..........
Write a file.
.. code-block:: python
from superdjango.utils import write_file
write_file("path/to/readme.txt", "This is a test.")
Math Helpers
------------
average
.......
Calculate the average of a given number of values, taking care to handle zero division.
.. code-block:: python
from superdjango.utils import average
values = [1, 2, 3, 4, 5]
print(average(values))
is_integer
..........
Indicates whether the given value is an integer. Saves a little typing.
.. code-block:: python
from superdjango.utils import is_integer
print(is_integer(17))
print(is_integer(17.5))
print(is_integer("17"))
print(is_integer("17", cast=True))
percentage
..........
Calculate the percentage that a portion makes up of a total.
.. code-block:: python
from superdjango.utils import percentage
p = percentage(50, 100)
print(p + "%")
String Operations
-----------------
base_convert
............
Convert a number between two bases of arbitrary digits.
.. code-block:: python
from superdjango.utils import base_convert
print(base_convert(12345))
camelcase_to_underscore
.......................
Convert a string from ``CamelCase`` to ``camel_case``.
.. code-block:: python
from superdjango.utils import camelcase_to_underscore
model_name = "ProjectTasks"
print(camelcase_to_underscore(model_name))
indent
......
Indent a string.
.. code-block:: python
from superdjango.utils import indent
text = "This text will be indented."
print(indent(text))
is_string
.........
Indicates whether the given value is a string. Saves a little typing.
.. code-block:: python
from superdjango.utils import is_string
print(is_string("testing"))
print(is_string("17"))
print(is_string(17))
strip_html_tags
...............
Strip HTML tags from a string.
.. code-block:: python
from superdjango.utils import strip_html_tags
html = "This string contains HTML tags.
"
print(strip_html_tags(html))
truncate
........
Get a truncated version of a string if if over the limit.
.. code-block:: python
from superdjango.utils import truncate
title = "This Title is Too Long to Be Displayed As Is"
print(truncate(title))
underscore_to_camelcase
.......................
Convert a string from ``camel_case`` to ``CamelCase`` .
.. code-block:: python
from superdjango.utils import underscore_to_camelcase
pattern_name = "project_detail"
print(underscore_to_camelcase(pattern_name))
underscore_to_title_case
........................
Convert a string from ``under_score_case`` to ``Title Case``.
.. code-block:: python
from superdjango.utils import underscore_to_title_case
pattern_name = "project_detail"
print(underscore_to_title_case(pattern_name))
Others
------
The File Class
..............
The :py:class:`File` class is a simple helper for working with the various attributes of a given file path.
For more robust handling of paths, see `pathlib`_.
.. _pathlib: https://docs.python.org/3/library/pathlib.html
.. code-block:: python
from superdjango.utils import File
f = File("/path/to/config.ini")
print("Path: %s" % f.path)
print("Directory: %s" % f.directory)
print("Name: %s" % f.name
print("Name Without Extension: %s" % f.basename)
print("Extension: %s" % f.extension)
smart_cast
..........
Intelligently cast the given value to a Python data type.
.. code-block:: python
from superdjango.utils import smart_cast
value = "123"
print(type(smart_cast(value)), smart_cast(value))
value = "yes"
print(type(smart_cast(value)), smart_cast(value))
.. _core-views:
Views
=====
|development| |library|
**Version:** 0.4.1-d
High-level, class-based views that may be used in practically all of the common use cases for Web application development.
Developer Reference: :ref:`core-views-developer`
**Provides**
- `Views `_ : base, mixins
Abstract
--------
High-level, class-based views that may be used in practically all of the common use cases for Web application
development. Originally inspired by `django-vanilla-views`_, SuperDjango's views provide a specific, opinionated, and
simpler alternative to Django's own class-based views.
.. _django-vanilla-views: http://django-vanilla-views.org
Install
-------
TODO: There are no install steps for views, though we should look at documenting the use of settings.
Usage
-----
TODO: Incorporate usage examples for generic views.