<commit_before>-----
About
-----

A drop in replacement for Django's built-in runserver command. Features include:

* An extendable interface for handling things such as real-time logging.
* Integration with the werkzeug interactive debugger.
* An improved runserver allowing you to process requests simultaneously.

.. image:: http://www.pastethat.com/media/files/2010/02/10/Screen_shot_2010-02-10_at_10.05.31_PM.png
   :alt: devserver screenshot


------------
Installation
------------

To install the latest stable version::

	pip install git+git://github.com/dcramer/django-devserver#egg=django-devserver


django-devserver has some optional dependancies, which we highly recommend installing.

* ``pip install sqlparse`` -- pretty SQL formatting
* ``pip install werkzeug`` -- interactive debugger
* ``pip install guppy`` -- tracks memory usage (required for MemoryUseModule)
* ``pip install line_profiler`` -- does line-by-line profiling (required for LineProfilerModule)

You will need to include ``devserver`` in your ``INSTALLED_APPS``::

	INSTALLED_APPS = (
	    'devserver',
	    ...
	)

Specify modules to load via the ``DEVSERVER_MODULES`` setting::

	DEVSERVER_MODULES = (
	    'devserver.modules.sql.SQLRealTimeModule',
	    'devserver.modules.sql.SQLSummaryModule',
	    'devserver.modules.profile.ProfileSummaryModule',

	    # Modules not enabled by default
	    'devserver.modules.ajax.AjaxDumpModule',
	    'devserver.modules.profile.MemoryUseModule',
	    'devserver.modules.cache.CacheSummaryModule',
	    'devserver.modules.profile.LineProfilerModule',
	)

You may also specify prefixes to skip processing for. By default, ``ADMIN_MEDIA_PREFIX`` and ``MEDIA_URL`` will be ignored (assuming ``MEDIA_URL`` is relative)::

	DEVSERVER_IGNORED_PREFIXES = ['/media', '/uploads']

-----
Usage
-----

Once installed, using the new runserver replacement is easy. You must specify verbosity of 0 to disable real-time log output::

	python manage.py runserver

Note: This will force ``settings.DEBUG`` to ``True``.

Please see ``python manage.py runserver --help`` for additional options.

You may also use devserver's middleware outside of the management command::

	MIDDLEWARE_CLASSES = (
		'devserver.middleware.DevServerMiddleware',
	)

-------
Modules
-------

django-devserver includes several modules by default, but is also extendable by 3rd party modules.

devserver.modules.sql.SQLRealTimeModule
  Outputs queries as they happen to the terminal, including time taken.
  
  Disable SQL query truncation (used in SQLRealTimeModule) with the ``DEVSERVER_TRUNCATE_SQL`` setting::
  
  	DEVSERVER_TRUNCATE_SQL = False

devserver.modules.sql.SQLSummaryModule
  Outputs a summary of your SQL usage.

devserver.modules.profile.ProfileSummaryModule
  Outputs a summary of the request performance.

devserver.modules.profile.MemoryUseModule
  Outputs a notice when memory use is increased (at the end of a request cycle).

devserver.modules.profile.LineProfilerModule
  Profiles view methods on a line by line basis. To profile a method, you must decorate it with devserver.modules.profile.devserver_profile. The decoration takes an optional argument ``follows`` which is a sequence of functions that   are called by your view function that you would also like profiled.

    @devserver_profile(follow=[foo, bar])
    def home(request):
        result['foo'] = foo()
        result['bar'] = bar()

devserver.modules.cache.CacheSummaryModule
  Outputs a summary of your cache calls at the end of the request.

devserver.modules.ajax.AjaxDumpModule
  Outputs the content of any AJAX responses
  
  Change the maximum response length to dump with the ``DEVSERVER_AJAX_CONTENT_LENGTH`` setting::
  
  	DEVSERVER_AJAX_CONTENT_LENGTH = 300

devserver.modules.request.SessionInfoModule
  Outputs information about the current session and user.



----------------
Building Modules
----------------

Building modules in devserver is quite simple. In fact, it resembles the middleware API almost identically.

Let's take a sample module, which simple tells us when a request has started, and when it has finished::

	from devserver.modules import DevServerModule
	
	class UselessModule(DevServerModule):
	    logger_name = 'useless'
	    
	    def process_request(self, request):
	        self.logger.info('Request started')
	    
	    def process_response(self, request, response):
	        self.logger.info('Request ended')

There are additional arguments which may be sent to logger methods, such as ``duration``::

	# duration is in milliseconds
	self.logger.info('message', duration=13.134)<commit_msg>Documentation formatting<commit_after>-----
About
-----

A drop in replacement for Django's built-in runserver command. Features include:

* An extendable interface for handling things such as real-time logging.
* Integration with the werkzeug interactive debugger.
* An improved runserver allowing you to process requests simultaneously.

.. image:: http://www.pastethat.com/media/files/2010/02/10/Screen_shot_2010-02-10_at_10.05.31_PM.png
   :alt: devserver screenshot


------------
Installation
------------

To install the latest stable version::

	pip install git+git://github.com/dcramer/django-devserver#egg=django-devserver


django-devserver has some optional dependancies, which we highly recommend installing.

* ``pip install sqlparse`` -- pretty SQL formatting
* ``pip install werkzeug`` -- interactive debugger
* ``pip install guppy`` -- tracks memory usage (required for MemoryUseModule)
* ``pip install line_profiler`` -- does line-by-line profiling (required for LineProfilerModule)

You will need to include ``devserver`` in your ``INSTALLED_APPS``::

	INSTALLED_APPS = (
	    'devserver',
	    ...
	)

Specify modules to load via the ``DEVSERVER_MODULES`` setting::

	DEVSERVER_MODULES = (
	    'devserver.modules.sql.SQLRealTimeModule',
	    'devserver.modules.sql.SQLSummaryModule',
	    'devserver.modules.profile.ProfileSummaryModule',

	    # Modules not enabled by default
	    'devserver.modules.ajax.AjaxDumpModule',
	    'devserver.modules.profile.MemoryUseModule',
	    'devserver.modules.cache.CacheSummaryModule',
	    'devserver.modules.profile.LineProfilerModule',
	)

You may also specify prefixes to skip processing for. By default, ``ADMIN_MEDIA_PREFIX`` and ``MEDIA_URL`` will be ignored (assuming ``MEDIA_URL`` is relative)::

	DEVSERVER_IGNORED_PREFIXES = ['/media', '/uploads']

-----
Usage
-----

Once installed, using the new runserver replacement is easy. You must specify verbosity of 0 to disable real-time log output::

	python manage.py runserver

Note: This will force ``settings.DEBUG`` to ``True``.

Please see ``python manage.py runserver --help`` for additional options.

You may also use devserver's middleware outside of the management command::

	MIDDLEWARE_CLASSES = (
		'devserver.middleware.DevServerMiddleware',
	)

-------
Modules
-------

django-devserver includes several modules by default, but is also extendable by 3rd party modules.

devserver.modules.sql.SQLRealTimeModule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  Outputs queries as they happen to the terminal, including time taken.
  
  Disable SQL query truncation (used in SQLRealTimeModule) with the ``DEVSERVER_TRUNCATE_SQL`` setting::
  
  	DEVSERVER_TRUNCATE_SQL = False

devserver.modules.sql.SQLSummaryModule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  Outputs a summary of your SQL usage.

devserver.modules.profile.ProfileSummaryModule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  Outputs a summary of the request performance.

devserver.modules.profile.MemoryUseModule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  Outputs a notice when memory use is increased (at the end of a request cycle).

devserver.modules.profile.LineProfilerModule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  Profiles view methods on a line by line basis. To profile a method, you must decorate it with devserver.modules.profile.devserver_profile. The decoration takes an optional argument ``follows`` which is a sequence of functions that   are called by your view function that you would also like profiled.

  An example of a decorated function::
  
  	@devserver_profile(follow=[foo, bar])
  	def home(request):
  	    result['foo'] = foo()
  	    result['bar'] = bar()


devserver.modules.cache.CacheSummaryModule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  Outputs a summary of your cache calls at the end of the request.

devserver.modules.ajax.AjaxDumpModule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  Outputs the content of any AJAX responses
  
  Change the maximum response length to dump with the ``DEVSERVER_AJAX_CONTENT_LENGTH`` setting::
  
  	DEVSERVER_AJAX_CONTENT_LENGTH = 300

devserver.modules.request.SessionInfoModule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  Outputs information about the current session and user.



----------------
Building Modules
----------------

Building modules in devserver is quite simple. In fact, it resembles the middleware API almost identically.

Let's take a sample module, which simple tells us when a request has started, and when it has finished::

	from devserver.modules import DevServerModule
	
	class UselessModule(DevServerModule):
	    logger_name = 'useless'
	    
	    def process_request(self, request):
	        self.logger.info('Request started')
	    
	    def process_response(self, request, response):
	        self.logger.info('Request ended')

There are additional arguments which may be sent to logger methods, such as ``duration``::

	# duration is in milliseconds
	self.logger.info('message', duration=13.134)
{'fraction_non_alphanumeric': 0.1284346378018318, 'fraction_numerical': 0.006661115736885929, 'mean_word_length': 4.144004282655247, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4345251', 'n_tokens_mistral': 2747, 'n_tokens_neox': 2562, 'n_words': 900}