From e19c9ccfcbd5b240c170df4b39a04af118d26e52 Mon Sep 17 00:00:00 2001 From: Adrian Holovaty Date: Sun, 6 Nov 2005 22:22:02 +0000 Subject: [PATCH] Reworded docstrings and settings documentation from [1068] git-svn-id: http://code.djangoproject.com/svn/django/trunk@1098 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- django/core/template/__init__.py | 81 +++++++++++++---------------- django/core/template/defaulttags.py | 9 +--- django/utils/functional.py | 51 ++++++------------ docs/settings.txt | 11 ++-- 4 files changed, 59 insertions(+), 93 deletions(-) diff --git a/django/core/template/__init__.py b/django/core/template/__init__.py index 2f1caf657fbdd..a501d6bbe8bcb 100644 --- a/django/core/template/__init__.py +++ b/django/core/template/__init__.py @@ -236,15 +236,12 @@ def delete_first_token(self): class TokenParser: """ - You need to subclass this class and implement the - top method to parse your template line. When instantiating - the parser, you pass in the line from the django template - parser. + Subclass this and implement the top() method to parse a template line. When + instantiating the parser, pass in the line from the Django template parser. - If your tag needs to know what tag name it was called with, - you find it in the tagname instance variable of the parser. + The parser's "tagname" instance-variable stores the name of the tag that + the filter was called with. """ - def __init__(self, subject): self.subject = subject self.pointer = 0 @@ -252,31 +249,21 @@ def __init__(self, subject): self.tagname = self.tag() def top(self): - """ - You need to overload this method to do the actual parsing - and return the result. - """ + "Overload this method to do the actual parsing and return the result." raise NotImplemented def more(self): - """ - This returns True if there is more stuff in the tag. - """ + "Returns True if there is more stuff in the tag." return self.pointer < len(self.subject) def back(self): - """ - This method undos the last microparser. This can be - used for lookahead and backtracking. - """ + "Undoes the last microparser. Use this for lookahead and backtracking." if not len(self.backout): raise TemplateSyntaxError, "back called without some previous parsing" self.pointer = self.backout.pop() def tag(self): - """ - This microparser just returns the next tag from the line. - """ + "A microparser that just returns the next tag from the line." subject = self.subject i = self.pointer if i >= len(subject): @@ -292,21 +279,18 @@ def tag(self): return s def value(self): - """ - This microparser parses for a value - some string constant or - variable name. - """ + "A microparser that parses for a value: some string constant or variable name." subject = self.subject i = self.pointer if i >= len(subject): - raise TemplateSyntaxError, "searching for value expected another value, found end of string: %s" % subject + raise TemplateSyntaxError, "Searching for value. Expected another value but found end of string: %s" % subject if subject[i] in ('"', "'"): p = i i += 1 while i < len(subject) and subject[i] != subject[p]: i += 1 if i >= len(subject): - raise TemplateSyntaxError, "searching for value, unexpected end of string in column %d: %s" % subject + raise TemplateSyntaxError, "Searching for value. Unexpected end of string in column %d: %s" % subject i += 1 res = subject[p:i] while i < len(subject) and subject[i] in (' ', '\t'): @@ -326,18 +310,19 @@ def value(self): return s class FilterParser: - """Parse a variable token and its optional filters (all as a single string), - and return a list of tuples of the filter name and arguments. - Sample: - >>> token = 'variable|default:"Default value"|date:"Y-m-d"' - >>> p = FilterParser(token) - >>> p.filters - [('default', 'Default value'), ('date', 'Y-m-d')] - >>> p.var - 'variable' - - This class should never be instantiated outside of the - get_filters_from_token helper function. + """ + Parses a variable token and its optional filters (all as a single string), + and return a list of tuples of the filter name and arguments. + Sample: + >>> token = 'variable|default:"Default value"|date:"Y-m-d"' + >>> p = FilterParser(token) + >>> p.filters + [('default', 'Default value'), ('date', 'Y-m-d')] + >>> p.var + 'variable' + + This class should never be instantiated outside of the + get_filters_from_token helper function. """ def __init__(self, s): self.s = s @@ -346,8 +331,8 @@ def __init__(self, s): self.filters = [] self.current_filter_name = None self.current_filter_arg = None - # First read the variable part - decide on wether we need - # to parse a string or a variable by peeking into the stream + # First read the variable part. Decide whether we need to parse a + # string or a variable by peeking into the stream. if self.peek_char() in ('_', '"', "'"): self.var = self.read_constant_string_token() else: @@ -378,15 +363,17 @@ def next_char(self): self.current = None def read_constant_string_token(self): - """Read a constant string that must be delimited by either " - or ' characters. The string is returned with it's delimiters.""" + """ + Reads a constant string that must be delimited by either " or ' + characters. The string is returned with its delimiters. + """ val = '' qchar = None i18n = False self.next_char() if self.current == '_': i18n = True - self.next_char() + self.next_char() if self.current != '(': raise TemplateSyntaxError, "Bad character (expecting '(') '%s'" % self.current self.next_char() @@ -409,8 +396,10 @@ def read_constant_string_token(self): return val def read_alphanumeric_token(self): - """Read a variable name or filter name, which are continuous strings of - alphanumeric characters + the underscore""" + """ + Reads a variable name or filter name, which are continuous strings of + alphanumeric characters + the underscore. + """ var = '' while 1: self.next_char() diff --git a/django/core/template/defaulttags.py b/django/core/template/defaulttags.py index d7c53fe947d10..8997d54b79527 100644 --- a/django/core/template/defaulttags.py +++ b/django/core/template/defaulttags.py @@ -2,10 +2,7 @@ from django.core.template import Node, NodeList, Template, Context, resolve_variable, resolve_variable_with_filters, get_filters_from_token, registered_filters from django.core.template import TemplateSyntaxError, VariableDoesNotExist, BLOCK_TAG_START, BLOCK_TAG_END, VARIABLE_TAG_START, VARIABLE_TAG_END, register_tag -from django.utils import translation - import sys -import re class CommentNode(Node): def render(self, context): @@ -531,12 +528,10 @@ def do_if(parser, token): {% endif %} {% if not athlete_list or coach_list %} - There are no athletes or there are some coaches (OK, so - writing English translations of boolean logic sounds - stupid; it's not my fault). + There are no athletes, or there are some coaches. {% endif %} - For simplicity, ``if`` tags do not allow ``and`` clauses; use nested ``if`` + For simplicity, ``if`` tags do not allow ``and`` clauses. Use nested ``if`` tags instead:: {% if athlete_list %} diff --git a/django/utils/functional.py b/django/utils/functional.py index 2b3ca8293ee55..f2ea12b1b2821 100644 --- a/django/utils/functional.py +++ b/django/utils/functional.py @@ -4,24 +4,17 @@ def _curried(*moreargs, **morekwargs): return _curried def lazy(func, *resultclasses): - """ - lazy turns any callable passed in into a lazy evaluated callable. - you need to give result classes or types - at least one is needed - so that the automatic forcing of the lazy evaluation code is - triggered. Results are not memoized - the function is evaluated - on every access. + Turns any callable into a lazy evaluated callable. You need to give result + classes or types -- at least one is needed so that the automatic forcing of + the lazy evaluation code is triggered. Results are not memoized; the + function is evaluated on every access. """ - class __proxy__: - - """ - This inner class encapsulates the code that should be evaluated - lazyly. On calling of one of the magic methods it will force - the evaluation and store the result - afterwards the result - is delivered directly. So the result is memoized. - """ - + # This inner class encapsulates the code that should be evaluated + # lazily. On calling of one of the magic methods it will force + # the evaluation and store the result. Afterwards, the result + # is delivered directly. So the result is memoized. def __init__(self, args, kw): self.__func = func self.__args = args @@ -31,35 +24,23 @@ def __init__(self, args, kw): self.__dispatch[resultclass] = {} for (k, v) in resultclass.__dict__.items(): setattr(self, k, self.__promise__(resultclass, k, v)) - + def __promise__(self, klass, funcname, func): - - """ - This function builds a wrapper around some magic method and - registers that magic method for the given type and methodname. - """ - + # Builds a wrapper around some magic method and registers that magic + # method for the given type and method name. def __wrapper__(*args, **kw): - """ - This wrapper function automatically triggers the evaluation of - a lazy value. It then applies the given magic method of the - result type. - """ + # Automatically triggers the evaluation of a lazy value and + # applies the given magic method of the result type. res = self.__func(*self.__args, **self.__kw) return self.__dispatch[type(res)][funcname](res, *args, **kw) - + if not self.__dispatch.has_key(klass): self.__dispatch[klass] = {} self.__dispatch[klass][funcname] = func return __wrapper__ - + def __wrapper__(*args, **kw): - """ - This wrapper function just creates the proxy object that is returned - instead of the actual value. - """ + # Creates the proxy object, instead of the actual value. return __proxy__(args, kw) return __wrapper__ - - diff --git a/docs/settings.txt b/docs/settings.txt index 1d65d44c88b30..e5dd32f4c1765 100644 --- a/docs/settings.txt +++ b/docs/settings.txt @@ -355,12 +355,13 @@ See http://www.thaiopensource.com/relaxng/jing.html . LANGUAGE_CODE ------------- -Default: ``'en'`` +Default: ``'en-us'`` -A string representing the language code for this installation. This should -be in locale format, that's 'en_US' for us-english. If you want to send -out the language in your HTML code, use the LANGUAGE_CODE attribute of the -request, instead, as the chosen language will depend on the browsers settings. +A string representing the language code for this installation. This should be +in standard language format. For example, U.S. English is ``"en-us"``. See the +`internationalization docs`_. + +.. _internationalization docs: http://www.djangoproject.com/documentation/i18n/ MANAGERS --------