diff -r 261778de26ff -r 620f9b141567 thirdparty/google_appengine/lib/django/docs/django-admin.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/thirdparty/google_appengine/lib/django/docs/django-admin.txt Tue Aug 26 21:49:54 2008 +0000 @@ -0,0 +1,544 @@ +============================= +django-admin.py and manage.py +============================= + +``django-admin.py`` is Django's command-line utility for administrative tasks. +This document outlines all it can do. + +In addition, ``manage.py`` is automatically created in each Django project. +``manage.py`` is a thin wrapper around ``django-admin.py`` that takes care of +two things for you before delegating to ``django-admin.py``: + + * It puts your project's package on ``sys.path``. + + * It sets the ``DJANGO_SETTINGS_MODULE`` environment variable so that it + points to your project's ``settings.py`` file. + +The ``django-admin.py`` script should be on your system path if you installed +Django via its ``setup.py`` utility. If it's not on your path, you can find it in +``site-packages/django/bin`` within your Python installation. Consider +symlinking it from some place on your path, such as ``/usr/local/bin``. + +For Windows users, who do not have symlinking functionality available, you +can copy ``django-admin.py`` to a location on your existing path or edit the +``PATH`` settings (under ``Settings - Control Panel - System - Advanced - Environment...``) +to point to its installed location. + +Generally, when working on a single Django project, it's easier to use +``manage.py``. Use ``django-admin.py`` with ``DJANGO_SETTINGS_MODULE``, or the +``--settings`` command line option, if you need to switch between multiple +Django settings files. + +Usage +===== + +``django-admin.py action [options]`` + +``manage.py action [options]`` + +``action`` should be one of the actions listed in this document. ``options``, +which is optional, should be zero or more of the options listed in this +document. + +Run ``django-admin.py --help`` to display a help message that includes a terse +list of all available actions and options. + +Most actions take a list of ``appname``s. An ``appname`` is the basename of the +package containing your models. For example, if your ``INSTALLED_APPS`` +contains the string ``'mysite.blog'``, the ``appname`` is ``blog``. + +Available actions +================= + +adminindex [appname appname ...] +-------------------------------- + +Prints the admin-index template snippet for the given appnames. + +Use admin-index template snippets if you want to customize the look and feel of +your admin's index page. See `Tutorial 2`_ for more information. + +.. _Tutorial 2: ../tutorial2/ + +createcachetable [tablename] +---------------------------- + +Creates a cache table named ``tablename`` for use with the database cache +backend. See the `cache documentation`_ for more information. + +.. _cache documentation: ../cache/ + +dbshell +------- + +Runs the command-line client for the database engine specified in your +``DATABASE_ENGINE`` setting, with the connection parameters specified in your +``DATABASE_USER``, ``DATABASE_PASSWORD``, etc., settings. + + * For PostgreSQL, this runs the ``psql`` command-line client. + * For MySQL, this runs the ``mysql`` command-line client. + * For SQLite, this runs the ``sqlite3`` command-line client. + +This command assumes the programs are on your ``PATH`` so that a simple call to +the program name (``psql``, ``mysql``, ``sqlite3``) will find the program in +the right place. There's no way to specify the location of the program +manually. + +diffsettings +------------ + +Displays differences between the current settings file and Django's default +settings. + +Settings that don't appear in the defaults are followed by ``"###"``. For +example, the default settings don't define ``ROOT_URLCONF``, so +``ROOT_URLCONF`` is followed by ``"###"`` in the output of ``diffsettings``. + +Note that Django's default settings live in ``django/conf/global_settings.py``, +if you're ever curious to see the full list of defaults. + +dumpdata [appname appname ...] +------------------------------ + +Output to standard output all data in the database associated with the named +application(s). + +By default, the database will be dumped in JSON format. If you want the output +to be in another format, use the ``--format`` option (e.g., ``format=xml``). +You may specify any Django serialization backend (including any user specified +serialization backends named in the ``SERIALIZATION_MODULES`` setting). + +If no application name is provided, all installed applications will be dumped. + +The output of ``dumpdata`` can be used as input for ``loaddata``. + +flush +----- + +Return the database to the state it was in immediately after syncdb was +executed. This means that all data will be removed from the database, any +post-synchronization handlers will be re-executed, and the ``initial_data`` +fixture will be re-installed. + +inspectdb +--------- + +Introspects the database tables in the database pointed-to by the +``DATABASE_NAME`` setting and outputs a Django model module (a ``models.py`` +file) to standard output. + +Use this if you have a legacy database with which you'd like to use Django. +The script will inspect the database and create a model for each table within +it. + +As you might expect, the created models will have an attribute for every field +in the table. Note that ``inspectdb`` has a few special cases in its field-name +output: + + * If ``inspectdb`` cannot map a column's type to a model field type, it'll + use ``TextField`` and will insert the Python comment + ``'This field type is a guess.'`` next to the field in the generated + model. + + * If the database column name is a Python reserved word (such as + ``'pass'``, ``'class'`` or ``'for'``), ``inspectdb`` will append + ``'_field'`` to the attribute name. For example, if a table has a column + ``'for'``, the generated model will have a field ``'for_field'``, with + the ``db_column`` attribute set to ``'for'``. ``inspectdb`` will insert + the Python comment + ``'Field renamed because it was a Python reserved word.'`` next to the + field. + +This feature is meant as a shortcut, not as definitive model generation. After +you run it, you'll want to look over the generated models yourself to make +customizations. In particular, you'll need to rearrange models' order, so that +models that refer to other models are ordered properly. + +Primary keys are automatically introspected for PostgreSQL, MySQL and +SQLite, in which case Django puts in the ``primary_key=True`` where +needed. + +``inspectdb`` works with PostgreSQL, MySQL and SQLite. Foreign-key detection +only works in PostgreSQL and with certain types of MySQL tables. + +loaddata [fixture fixture ...] +------------------------------ + +Searches for and loads the contents of the named fixture into the database. + +A *Fixture* is a collection of files that contain the serialized contents of +the database. Each fixture has a unique name; however, the files that +comprise the fixture can be distributed over multiple directories, in +multiple applications. + +Django will search in three locations for fixtures: + + 1. In the ``fixtures`` directory of every installed application + 2. In any directory named in the ``FIXTURE_DIRS`` setting + 3. In the literal path named by the fixture + +Django will load any and all fixtures it finds in these locations that match +the provided fixture names. + +If the named fixture has a file extension, only fixtures of that type +will be loaded. For example:: + + django-admin.py loaddata mydata.json + +would only load JSON fixtures called ``mydata``. The fixture extension +must correspond to the registered name of a serializer (e.g., ``json`` or +``xml``). + +If you omit the extension, Django will search all available fixture types +for a matching fixture. For example:: + + django-admin.py loaddata mydata + +would look for any fixture of any fixture type called ``mydata``. If a fixture +directory contained ``mydata.json``, that fixture would be loaded +as a JSON fixture. However, if two fixtures with the same name but different +fixture type are discovered (for example, if ``mydata.json`` and +``mydata.xml`` were found in the same fixture directory), fixture +installation will be aborted, and any data installed in the call to +``loaddata`` will be removed from the database. + +The fixtures that are named can include directory components. These +directories will be included in the search path. For example:: + + django-admin.py loaddata foo/bar/mydata.json + +would search ``/fixtures/foo/bar/mydata.json`` for each installed +application, ``/foo/bar/mydata.json`` for each directory in +``FIXTURE_DIRS``, and the literal path ``foo/bar/mydata.json``. + +Note that the order in which fixture files are processed is undefined. However, +all fixture data is installed as a single transaction, so data in +one fixture can reference data in another fixture. If the database backend +supports row-level constraints, these constraints will be checked at the +end of the transaction. + +.. admonition:: MySQL and Fixtures + + Unfortunately, MySQL isn't capable of completely supporting all the + features of Django fixtures. If you use MyISAM tables, MySQL doesn't + support transactions or constraints, so you won't get a rollback if + multiple transaction files are found, or validation of fixture data. + If you use InnoDB tables, you won't be able to have any forward + references in your data files - MySQL doesn't provide a mechanism to + defer checking of row constraints until a transaction is committed. + +reset [appname appname ...] +--------------------------- +Executes the equivalent of ``sqlreset`` for the given appnames. + +runfcgi [options] +----------------- +Starts a set of FastCGI processes suitable for use with any web server +which supports the FastCGI protocol. See the `FastCGI deployment +documentation`_ for details. Requires the Python FastCGI module from +`flup`_. + +.. _FastCGI deployment documentation: ../fastcgi/ +.. _flup: http://www.saddi.com/software/flup/ + +runserver [optional port number, or ipaddr:port] +------------------------------------------------ + +Starts a lightweight development Web server on the local machine. By default, +the server runs on port 8000 on the IP address 127.0.0.1. You can pass in an +IP address and port number explicitly. + +If you run this script as a user with normal privileges (recommended), you +might not have access to start a port on a low port number. Low port numbers +are reserved for the superuser (root). + +DO NOT USE THIS SERVER IN A PRODUCTION SETTING. It has not gone through +security audits or performance tests. (And that's how it's gonna stay. We're in +the business of making Web frameworks, not Web servers, so improving this +server to be able to handle a production environment is outside the scope of +Django.) + +The development server automatically reloads Python code for each request, as +needed. You don't need to restart the server for code changes to take effect. + +When you start the server, and each time you change Python code while the +server is running, the server will validate all of your installed models. (See +the ``validate`` command below.) If the validator finds errors, it will print +them to standard output, but it won't stop the server. + +You can run as many servers as you want, as long as they're on separate ports. +Just execute ``django-admin.py runserver`` more than once. + +Note that the default IP address, 127.0.0.1, is not accessible from other +machines on your network. To make your development server viewable to other +machines on the network, use its own IP address (e.g. ``192.168.2.1``) or +``0.0.0.0``. + +Examples: +~~~~~~~~~ + +Port 7000 on IP address 127.0.0.1:: + + django-admin.py runserver 7000 + +Port 7000 on IP address 1.2.3.4:: + + django-admin.py runserver 1.2.3.4:7000 + +Serving static files with the development server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, the development server doesn't serve any static files for your site +(such as CSS files, images, things under ``MEDIA_ROOT_URL`` and so forth). If +you want to configure Django to serve static media, read the `serving static files`_ +documentation. + +.. _serving static files: ../static_files/ + +Turning off auto-reload +~~~~~~~~~~~~~~~~~~~~~~~ + +To disable auto-reloading of code while the development server is running, use the +``--noreload`` option, like so:: + + django-admin.py runserver --noreload + +shell +----- + +Starts the Python interactive interpreter. + +Django will use IPython_, if it's installed. If you have IPython installed and +want to force use of the "plain" Python interpreter, use the ``--plain`` +option, like so:: + + django-admin.py shell --plain + +.. _IPython: http://ipython.scipy.org/ + +sql [appname appname ...] +------------------------- + +Prints the CREATE TABLE SQL statements for the given appnames. + +sqlall [appname appname ...] +---------------------------- + +Prints the CREATE TABLE and initial-data SQL statements for the given appnames. + +Refer to the description of ``sqlinitialdata`` for an explanation of how to +specify initial data. + +sqlclear [appname appname ...] +-------------------------------------- + +Prints the DROP TABLE SQL statements for the given appnames. + +sqlcustom [appname appname ...] +------------------------------- + +Prints the custom SQL statements for the given appnames. + +For each model in each specified app, this command looks for the file +``/sql/.sql``, where ```` is the given appname and +```` is the model's name in lowercase. For example, if you have an +app ``news`` that includes a ``Story`` model, ``sqlinitialdata`` will attempt +to read a file ``news/sql/story.sql`` and append it to the output of this +command. + +Each of the SQL files, if given, is expected to contain valid SQL. The SQL +files are piped directly into the database after all of the models' +table-creation statements have been executed. Use this SQL hook to make any +table modifications, or insert any SQL functions into the database. + +Note that the order in which the SQL files are processed is undefined. + +sqlindexes [appname appname ...] +---------------------------------------- + +Prints the CREATE INDEX SQL statements for the given appnames. + +sqlreset [appname appname ...] +-------------------------------------- + +Prints the DROP TABLE SQL, then the CREATE TABLE SQL, for the given appnames. + +sqlsequencereset [appname appname ...] +---------------------------------------------- + +Prints the SQL statements for resetting PostgreSQL sequences for the given +appnames. + +See http://simon.incutio.com/archive/2004/04/21/postgres for more information. + +startapp [appname] +------------------ + +Creates a Django app directory structure for the given app name in the current +directory. + +startproject [projectname] +-------------------------- + +Creates a Django project directory structure for the given project name in the +current directory. + +syncdb +------ + +Creates the database tables for all apps in ``INSTALLED_APPS`` whose tables +have not already been created. + +Use this command when you've added new applications to your project and want to +install them in the database. This includes any apps shipped with Django that +might be in ``INSTALLED_APPS`` by default. When you start a new project, run +this command to install the default apps. + +If you're installing the ``django.contrib.auth`` application, ``syncdb`` will +give you the option of creating a superuser immediately. + +``syncdb`` will also search for and install any fixture named ``initial_data``. +See the documentation for ``loaddata`` for details on the specification of +fixture data files. + +test +---- + +Discover and run tests for all installed models. See `Testing Django applications`_ for more information. + +.. _testing django applications: ../testing/ + +validate +-------- + +Validates all installed models (according to the ``INSTALLED_APPS`` setting) +and prints validation errors to standard output. + +Available options +================= + +--settings +---------- + +Example usage:: + + django-admin.py syncdb --settings=mysite.settings + +Explicitly specifies the settings module to use. The settings module should be +in Python package syntax, e.g. ``mysite.settings``. If this isn't provided, +``django-admin.py`` will use the ``DJANGO_SETTINGS_MODULE`` environment +variable. + +Note that this option is unnecessary in ``manage.py``, because it takes care of +setting ``DJANGO_SETTINGS_MODULE`` for you. + +--pythonpath +------------ + +Example usage:: + + django-admin.py syncdb --pythonpath='/home/djangoprojects/myproject' + +Adds the given filesystem path to the Python `import search path`_. If this +isn't provided, ``django-admin.py`` will use the ``PYTHONPATH`` environment +variable. + +Note that this option is unnecessary in ``manage.py``, because it takes care of +setting the Python path for you. + +.. _import search path: http://diveintopython.org/getting_to_know_python/everything_is_an_object.html + +--format +-------- + +Example usage:: + + django-admin.py dumpdata --format=xml + +Specifies the output format that will be used. The name provided must be the name +of a registered serializer. + +--help +------ + +Displays a help message that includes a terse list of all available actions and +options. + +--indent +-------- + +Example usage:: + + django-admin.py dumpdata --indent=4 + +Specifies the number of spaces that will be used for indentation when +pretty-printing output. By default, output will *not* be pretty-printed. +Pretty-printing will only be enabled if the indent option is provided. + +--noinput +--------- + +Inform django-admin that the user should NOT be prompted for any input. Useful +if the django-admin script will be executed as an unattended, automated +script. + +--noreload +---------- + +Disable the use of the auto-reloader when running the development server. + +--version +--------- + +Displays the current Django version. + +Example output:: + + 0.9.1 + 0.9.1 (SVN) + +--verbosity +----------- + +Example usage:: + + django-admin.py syncdb --verbosity=2 + +Verbosity determines the amount of notification and debug information that +will be printed to the console. '0' is no output, '1' is normal output, +and `2` is verbose output. + +--adminmedia +------------ + +Example usage:: + django-admin.py manage.py --adminmedia=/tmp/new-admin-style/ + +Tells Django where to find the various CSS and JavaScript files for the admin +interface when running the development server. Normally these files are served +out of the Django source tree, but because some designers customize these files +for their site, this option allows you to test against custom versions. + +Extra niceties +============== + +Syntax coloring +--------------- + +The ``django-admin.py`` / ``manage.py`` commands that output SQL to standard +output will use pretty color-coded output if your terminal supports +ANSI-colored output. It won't use the color codes if you're piping the +command's output to another program. + +Bash completion +--------------- + +If you use the Bash shell, consider installing the Django bash completion +script, which lives in ``extras/django_bash_completion`` in the Django +distribution. It enables tab-completion of ``django-admin.py`` and +``manage.py`` commands, so you can, for instance... + + * Type ``django-admin.py``. + * Press [TAB] to see all available options. + * Type ``sql``, then [TAB], to see all available options whose names start + with ``sql``.