From 8284217593d5ea3d4bdeaed1e146fa94578b7999 Mon Sep 17 00:00:00 2001 From: defuz Date: Wed, 5 Nov 2014 06:04:58 +0300 Subject: [PATCH] docs: ``True``, ``False`` and ``None`` --- CHANGES | 10 +++--- docs/api.rst | 18 +++++------ docs/config.rst | 10 +++--- docs/patterns/appdispatch.rst | 2 +- docs/patterns/caching.rst | 2 +- docs/patterns/distribute.rst | 2 +- docs/patterns/mongokit.rst | 2 +- docs/patterns/viewdecorators.rst | 18 +++++------ docs/patterns/wtforms.rst | 2 +- docs/styleguide.rst | 2 +- docs/tutorial/dbcon.rst | 2 +- docs/tutorial/views.rst | 4 +-- flask/app.py | 52 ++++++++++++++++---------------- flask/blueprints.py | 2 +- flask/config.py | 8 ++--- flask/ctx.py | 2 +- flask/helpers.py | 28 ++++++++--------- flask/sessions.py | 18 +++++------ flask/wrappers.py | 14 ++++----- 19 files changed, 99 insertions(+), 99 deletions(-) diff --git a/CHANGES b/CHANGES index 8366bdb3..c5eb7bbc 100644 --- a/CHANGES +++ b/CHANGES @@ -12,9 +12,9 @@ Version 1.0 additional keyword arguments to the constructor of :attr:`flask.Flask.test_client_class`. - Added ``SESSION_REFRESH_EACH_REQUEST`` config key that controls the - set-cookie behavior. If set to `True` a permanent session will be + set-cookie behavior. If set to ``True`` a permanent session will be refreshed each request and get their lifetime extended, if set to - `False` it will only be modified if the session actually modifies. + ``False`` it will only be modified if the session actually modifies. Non permanent sessions are not affected by this and will always expire if the browser window closes. - Made Flask support custom JSON mimetypes for incoming data. @@ -183,7 +183,7 @@ Released on July 1st 2012, codename Campari. explicitly. - Unregister a circular dependency between the WSGI environment and the request object when shutting down the request. This means that - environ ``werkzeug.request`` will be `None` after the response was + environ ``werkzeug.request`` will be ``None`` after the response was returned to the WSGI server but has the advantage that the garbage collector is not needed on CPython to tear down the request unless the user created circular dependencies themselves. @@ -204,8 +204,8 @@ Released on July 1st 2012, codename Campari. - The :func:`flask.get_flashed_messages` function now allows rendering flashed message categories in separate blocks, through a ``category_filter`` argument. -- The :meth:`flask.Flask.run` method now accepts `None` for `host` and `port` - arguments, using default values when `None`. This allows for calling run +- The :meth:`flask.Flask.run` method now accepts ``None`` for `host` and `port` + arguments, using default values when ``None``. This allows for calling run using configuration values, e.g. ``app.run(app.config.get('MYHOST'), app.config.get('MYPORT'))``, with proper behavior whether or not a config file is provided. diff --git a/docs/api.rst b/docs/api.rst index 81543026..558fd704 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -115,7 +115,7 @@ Incoming Request Data .. attribute:: is_xhr - `True` if the request was triggered via a JavaScript + ``True`` if the request was triggered via a JavaScript `XMLHttpRequest`. This only works with libraries that support the ``X-Requested-With`` header and set it to `XMLHttpRequest`. Libraries that do that are prototype, jQuery and Mochikit and @@ -178,14 +178,14 @@ To access the current session you can use the :class:`session` object: .. attribute:: new - `True` if the session is new, `False` otherwise. + ``True`` if the session is new, ``False`` otherwise. .. attribute:: modified - `True` if the session object detected a modification. Be advised + ``True`` if the session object detected a modification. Be advised that modifications on mutable structures are not picked up automatically, in that situation you have to explicitly set the - attribute to `True` yourself. Here an example:: + attribute to ``True`` yourself. Here an example:: # this change is not picked up because a mutable object (here # a list) is changed. @@ -195,9 +195,9 @@ To access the current session you can use the :class:`session` object: .. attribute:: permanent - If set to `True` the session lives for + If set to ``True`` the session lives for :attr:`~flask.Flask.permanent_session_lifetime` seconds. The - default is 31 days. If set to `False` (which is the default) the + default is 31 days. If set to ``False`` (which is the default) the session will be deleted when the user closes the browser. @@ -279,7 +279,7 @@ thing, like it does for :class:`request` and :class:`session`. pattern for testing. Additionally as of 0.10 you can use the :meth:`get` method to - get an attribute or `None` (or the second argument) if it's not set. + get an attribute or ``None`` (or the second argument) if it's not set. These two usages are now equivalent:: user = getattr(flask.g, 'user', None) @@ -516,7 +516,7 @@ Signals .. data:: signals_available - `True` if the signaling system is available. This is the case + ``True`` if the signaling system is available. This is the case when `blinker`_ is installed. .. data:: template_rendered @@ -782,7 +782,7 @@ Command Line Interface A special decorator that informs a click callback to be passed the script info object as first argument. This is normally not useful unless you implement very special commands like the run command which - does not want the application to be loaded yet. + does not want the application to be loaded yet. .. autodata:: run_command diff --git a/docs/config.rst b/docs/config.rst index c8468d02..c3909d85 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -56,7 +56,7 @@ The following configuration values are used internally by Flask: ``TESTING`` enable/disable testing mode ``PROPAGATE_EXCEPTIONS`` explicitly enable or disable the propagation of exceptions. If not set or - explicitly set to `None` this is + explicitly set to ``None`` this is implicitly true if either `TESTING` or `DEBUG` is true. ``PRESERVE_CONTEXT_ON_EXCEPTION`` By default if the application is in @@ -80,20 +80,20 @@ The following configuration values are used internally by Flask: that is not set for ``'/'``. ``SESSION_COOKIE_HTTPONLY`` controls if the cookie should be set with the httponly flag. Defaults to - `True`. + ``True``. ``SESSION_COOKIE_SECURE`` controls if the cookie should be set with the secure flag. Defaults to - `False`. + ``False``. ``PERMANENT_SESSION_LIFETIME`` the lifetime of a permanent session as :class:`datetime.timedelta` object. Starting with Flask 0.8 this can also be an integer representing seconds. ``SESSION_REFRESH_EACH_REQUEST`` this flag controls how permanent - sessions are refreshed. If set to `True` + sessions are refreshed. If set to ``True`` (which is the default) then the cookie is refreshed each request which automatically bumps the lifetime. If - set to `False` a `set-cookie` header is + set to ``False`` a `set-cookie` header is only sent if the session is modified. Non permanent sessions are not affected by this. diff --git a/docs/patterns/appdispatch.rst b/docs/patterns/appdispatch.rst index 4f6dc18b..0060f361 100644 --- a/docs/patterns/appdispatch.rst +++ b/docs/patterns/appdispatch.rst @@ -176,7 +176,7 @@ request path up to the first slash:: return app(environ, start_response) The big difference between this and the subdomain one is that this one -falls back to another application if the creator function returns `None`:: +falls back to another application if the creator function returns ``None``:: from myapplication import create_app, default_app, get_user_for_prefix diff --git a/docs/patterns/caching.rst b/docs/patterns/caching.rst index 97e0f35d..4ca8ea42 100644 --- a/docs/patterns/caching.rst +++ b/docs/patterns/caching.rst @@ -50,7 +50,7 @@ operations: :meth:`~werkzeug.contrib.cache.BaseCache.get` and To get an item from the cache call :meth:`~werkzeug.contrib.cache.BaseCache.get` with a string as key name. If something is in the cache, it is returned. Otherwise that function -will return `None`:: +will return ``None``:: rv = cache.get('my-item') diff --git a/docs/patterns/distribute.rst b/docs/patterns/distribute.rst index aa53e685..466032dc 100644 --- a/docs/patterns/distribute.rst +++ b/docs/patterns/distribute.rst @@ -109,7 +109,7 @@ your tarball:: Don't forget that even if you enlist them in your `MANIFEST.in` file, they won't be installed for you unless you set the `include_package_data` -parameter of the `setup` function to `True`! +parameter of the `setup` function to ``True``! Declaring Dependencies diff --git a/docs/patterns/mongokit.rst b/docs/patterns/mongokit.rst index fa9dd2fb..db12fda6 100644 --- a/docs/patterns/mongokit.rst +++ b/docs/patterns/mongokit.rst @@ -76,7 +76,7 @@ Here is an example document (put this also into `app.py`, e.g.):: This example shows you how to define your schema (named structure), a validator for the maximum character length and uses a special MongoKit feature called `use_dot_notation`. Per default MongoKit behaves like a python -dictionary but with `use_dot_notation` set to `True` you can use your +dictionary but with `use_dot_notation` set to ``True`` you can use your documents like you use models in nearly any other ORM by using dots to separate between attributes. diff --git a/docs/patterns/viewdecorators.rst b/docs/patterns/viewdecorators.rst index 0e523cfd..97e6871d 100644 --- a/docs/patterns/viewdecorators.rst +++ b/docs/patterns/viewdecorators.rst @@ -23,7 +23,7 @@ often forgotten, but you don't have to do that by hand, there is a function for that that is used like a decorator (:func:`functools.wraps`). This example assumes that the login page is called ``'login'`` and that -the current user is stored as `g.user` and `None` if there is no-one +the current user is stored as `g.user` and ``None`` if there is no-one logged in:: from functools import wraps @@ -120,7 +120,7 @@ As you can see, if no template name is provided it will use the endpoint of the URL map with dots converted to slashes + ``'.html'``. Otherwise the provided template name is used. When the decorated function returns, the dictionary returned is passed to the template rendering function. If -`None` is returned, an empty dictionary is assumed, if something else than +``None`` is returned, an empty dictionary is assumed, if something else than a dictionary is returned we return it from the function unchanged. That way you can still use the redirect function or return simple strings. @@ -151,15 +151,15 @@ Endpoint Decorator ------------------ When you want to use the werkzeug routing system for more flexibility you -need to map the endpoint as defined in the :class:`~werkzeug.routing.Rule` -to a view function. This is possible with this decorator. For example:: +need to map the endpoint as defined in the :class:`~werkzeug.routing.Rule` +to a view function. This is possible with this decorator. For example:: from flask import Flask from werkzeug.routing import Rule - app = Flask(__name__) - app.url_map.add(Rule('/', endpoint='index')) + app = Flask(__name__) + app.url_map.add(Rule('/', endpoint='index')) - @app.endpoint('index') - def my_index(): - return "Hello world" + @app.endpoint('index') + def my_index(): + return "Hello world" diff --git a/docs/patterns/wtforms.rst b/docs/patterns/wtforms.rst index 49bdbd43..49c1ca72 100644 --- a/docs/patterns/wtforms.rst +++ b/docs/patterns/wtforms.rst @@ -64,7 +64,7 @@ Things to remember: the data is submitted via the HTTP `POST` method and :attr:`~flask.request.args` if the data is submitted as `GET`. 2. to validate the data, call the :func:`~wtforms.form.Form.validate` - method which will return `True` if the data validates, `False` + method which will return ``True`` if the data validates, ``False`` otherwise. 3. to access individual values from the form, access `form..data`. diff --git a/docs/styleguide.rst b/docs/styleguide.rst index d46ecd04..e03e4ef5 100644 --- a/docs/styleguide.rst +++ b/docs/styleguide.rst @@ -108,7 +108,7 @@ Comparisons: - against arbitrary types: ``==`` and ``!=`` - against singletons with ``is`` and ``is not`` (eg: ``foo is not None``) - - never compare something with `True` or `False` (for example never + - never compare something with ``True`` or ``False`` (for example never do ``foo == False``, do ``not foo`` instead) Negated containment checks: diff --git a/docs/tutorial/dbcon.rst b/docs/tutorial/dbcon.rst index 00f6c32e..9b60a40f 100644 --- a/docs/tutorial/dbcon.rst +++ b/docs/tutorial/dbcon.rst @@ -53,7 +53,7 @@ every time the app context tears down. So what does this mean? Essentially the app context is created before the request comes in and is destroyed (torn down) whenever the request finishes. A teardown can happen because of two reasons: either everything went well (the error -parameter will be `None`) or an exception happened in which case the error +parameter will be ``None``) or an exception happened in which case the error is passed to the teardown function. Curious about what these contexts mean? Have a look at the diff --git a/docs/tutorial/views.rst b/docs/tutorial/views.rst index 69c1c161..35c8a2c8 100644 --- a/docs/tutorial/views.rst +++ b/docs/tutorial/views.rst @@ -46,7 +46,7 @@ redirect back to the `show_entries` page:: return redirect(url_for('show_entries')) Note that we check that the user is logged in here (the `logged_in` key is -present in the session and `True`). +present in the session and ``True``). .. admonition:: Security Note @@ -61,7 +61,7 @@ Login and Logout These functions are used to sign the user in and out. Login checks the username and password against the ones from the configuration and sets the `logged_in` key in the session. If the user logged in successfully, that -key is set to `True`, and the user is redirected back to the `show_entries` +key is set to ``True``, and the user is redirected back to the `show_entries` page. In addition, a message is flashed that informs the user that he or she was logged in successfully. If an error occurred, the template is notified about that, and the user is asked again:: diff --git a/flask/app.py b/flask/app.py index 76f73366..4d7911a6 100644 --- a/flask/app.py +++ b/flask/app.py @@ -135,7 +135,7 @@ class Flask(_PackageBoundObject): By default the folder ``'instance'`` next to the package or module is assumed to be the instance path. - :param instance_relative_config: if set to `True` relative filenames + :param instance_relative_config: if set to ``True`` relative filenames for loading the config are assumed to be relative to the instance path instead of the application root. @@ -193,16 +193,16 @@ class Flask(_PackageBoundObject): #: .. versionadded:: 1.0 config_class = Config - #: The debug flag. Set this to `True` to enable debugging of the + #: The debug flag. Set this to ``True`` to enable debugging of the #: application. In debug mode the debugger will kick in when an unhandled #: exception occurs and the integrated server will automatically reload #: the application if changes in the code are detected. #: #: This attribute can also be configured from the config with the `DEBUG` - #: configuration key. Defaults to `False`. + #: configuration key. Defaults to ``False``. debug = ConfigAttribute('DEBUG') - #: The testing flag. Set this to `True` to enable the test mode of + #: The testing flag. Set this to ``True`` to enable the test mode of #: Flask extensions (and in the future probably also Flask itself). #: For example this might activate unittest helpers that have an #: additional runtime cost which should not be enabled by default. @@ -211,7 +211,7 @@ class Flask(_PackageBoundObject): #: default it's implicitly enabled. #: #: This attribute can also be configured from the config with the - #: `TESTING` configuration key. Defaults to `False`. + #: `TESTING` configuration key. Defaults to ``False``. testing = ConfigAttribute('TESTING') #: If a secret key is set, cryptographic components can use this to @@ -219,7 +219,7 @@ class Flask(_PackageBoundObject): #: when you want to use the secure cookie for instance. #: #: This attribute can also be configured from the config with the - #: `SECRET_KEY` configuration key. Defaults to `None`. + #: `SECRET_KEY` configuration key. Defaults to ``None``. secret_key = ConfigAttribute('SECRET_KEY') #: The secure cookie uses this for the name of the session cookie. @@ -245,7 +245,7 @@ class Flask(_PackageBoundObject): #: .. versionadded:: 0.2 #: #: This attribute can also be configured from the config with the - #: `USE_X_SENDFILE` configuration key. Defaults to `False`. + #: `USE_X_SENDFILE` configuration key. Defaults to ``False``. use_x_sendfile = ConfigAttribute('USE_X_SENDFILE') #: The name of the logger to use. By default the logger name is the @@ -364,11 +364,11 @@ class Flask(_PackageBoundObject): # :attr:`error_handler_spec` shall be used now. self._error_handlers = {} - #: A dictionary of all registered error handlers. The key is `None` + #: A dictionary of all registered error handlers. The key is ``None`` #: for error handlers active on the application, otherwise the key is #: the name of the blueprint. Each key points to another dictionary #: where the key is the status code of the http exception. The - #: special key `None` points to a list of tuples where the first item + #: special key ``None`` points to a list of tuples where the first item #: is the class for the instance check and the second the error handler #: function. #: @@ -379,7 +379,7 @@ class Flask(_PackageBoundObject): #: A list of functions that are called when :meth:`url_for` raises a #: :exc:`~werkzeug.routing.BuildError`. Each function registered here #: is called with `error`, `endpoint` and `values`. If a function - #: returns `None` or raises a `BuildError` the next function is + #: returns ``None`` or raises a `BuildError` the next function is #: tried. #: #: .. versionadded:: 0.9 @@ -387,7 +387,7 @@ class Flask(_PackageBoundObject): #: A dictionary with lists of functions that should be called at the #: beginning of the request. The key of the dictionary is the name of - #: the blueprint this function is active for, `None` for all requests. + #: the blueprint this function is active for, ``None`` for all requests. #: This can for example be used to open database connections or #: getting hold of the currently logged in user. To register a #: function here, use the :meth:`before_request` decorator. @@ -402,7 +402,7 @@ class Flask(_PackageBoundObject): #: A dictionary with lists of functions that should be called after #: each request. The key of the dictionary is the name of the blueprint - #: this function is active for, `None` for all requests. This can for + #: this function is active for, ``None`` for all requests. This can for #: example be used to open database connections or getting hold of the #: currently logged in user. To register a function here, use the #: :meth:`after_request` decorator. @@ -411,7 +411,7 @@ class Flask(_PackageBoundObject): #: A dictionary with lists of functions that are called after #: each request, even if an exception has occurred. The key of the #: dictionary is the name of the blueprint this function is active for, - #: `None` for all requests. These functions are not allowed to modify + #: ``None`` for all requests. These functions are not allowed to modify #: the request, and their return values are ignored. If an exception #: occurred while processing the request, it gets passed to each #: teardown_request function. To register a function here, use the @@ -431,7 +431,7 @@ class Flask(_PackageBoundObject): #: A dictionary with lists of functions that can be used as URL #: value processor functions. Whenever a URL is built these functions #: are called to modify the dictionary of values in place. The key - #: `None` here is used for application wide + #: ``None`` here is used for application wide #: callbacks, otherwise the key is the name of the blueprint. #: Each of these functions has the chance to modify the dictionary #: @@ -439,7 +439,7 @@ class Flask(_PackageBoundObject): self.url_value_preprocessors = {} #: A dictionary with lists of functions that can be used as URL value - #: preprocessors. The key `None` here is used for application wide + #: preprocessors. The key ``None`` here is used for application wide #: callbacks, otherwise the key is the name of the blueprint. #: Each of these functions has the chance to modify the dictionary #: of URL values before they are used as the keyword arguments of the @@ -452,7 +452,7 @@ class Flask(_PackageBoundObject): #: A dictionary with list of functions that are called without argument #: to populate the template context. The key of the dictionary is the - #: name of the blueprint this function is active for, `None` for all + #: name of the blueprint this function is active for, ``None`` for all #: requests. Each returns a dictionary that the template context is #: updated with. To register a function here, use the #: :meth:`context_processor` decorator. @@ -612,7 +612,7 @@ class Flask(_PackageBoundObject): @property def got_first_request(self): - """This attribute is set to `True` if the application started + """This attribute is set to ``True`` if the application started handling the first request. .. versionadded:: 0.8 @@ -715,7 +715,7 @@ class Flask(_PackageBoundObject): """ def select_jinja_autoescape(self, filename): - """Returns `True` if autoescaping should be active for the given + """Returns ``True`` if autoescaping should be active for the given template name. .. versionadded:: 0.5 @@ -782,7 +782,7 @@ class Flask(_PackageBoundObject): unless it is in debug mode. As such to enable just the interactive debugger without the code reloading, you have to invoke :meth:`run` with ``debug=True`` and ``use_reloader=False``. - Setting ``use_debugger`` to `True` without being in debug mode + Setting ``use_debugger`` to ``True`` without being in debug mode won't catch any exceptions because there won't be any to catch. @@ -1102,8 +1102,8 @@ class Flask(_PackageBoundObject): however is discouraged as it requires fiddling with nested dictionaries and the special case for arbitrary exception types. - The first `None` refers to the active blueprint. If the error - handler should be application wide `None` shall be used. + The first ``None`` refers to the active blueprint. If the error + handler should be application wide ``None`` shall be used. .. versionadded:: 0.7 Use :meth:`register_error_handler` instead of modifying @@ -1392,12 +1392,12 @@ class Flask(_PackageBoundObject): def trap_http_exception(self, e): """Checks if an HTTP exception should be trapped or not. By default - this will return `False` for all exceptions except for a bad request - key error if ``TRAP_BAD_REQUEST_ERRORS`` is set to `True`. It - also returns `True` if ``TRAP_HTTP_EXCEPTIONS`` is set to `True`. + this will return ``False`` for all exceptions except for a bad request + key error if ``TRAP_BAD_REQUEST_ERRORS`` is set to ``True``. It + also returns ``True`` if ``TRAP_HTTP_EXCEPTIONS`` is set to ``True``. This is called for all HTTP exceptions raised by a view function. - If it returns `True` for any exception the error handler for this + If it returns ``True`` for any exception the error handler for this exception is not called and it shows up as regular exception in the traceback. This is helpful for debugging implicitly raised HTTP exceptions. @@ -1584,7 +1584,7 @@ class Flask(_PackageBoundObject): def should_ignore_error(self, error): """This is called to figure out if an error should be ignored or not as far as the teardown system is concerned. If this - function returns `True` then the teardown handlers will not be + function returns ``True`` then the teardown handlers will not be passed the error. .. versionadded:: 0.10 diff --git a/flask/blueprints.py b/flask/blueprints.py index 924c5441..3d2e7641 100644 --- a/flask/blueprints.py +++ b/flask/blueprints.py @@ -42,7 +42,7 @@ class BlueprintSetupState(object): if subdomain is None: subdomain = self.blueprint.subdomain - #: The subdomain that the blueprint should be active for, `None` + #: The subdomain that the blueprint should be active for, ``None`` #: otherwise. self.subdomain = subdomain diff --git a/flask/config.py b/flask/config.py index 6d7e8683..774e00df 100644 --- a/flask/config.py +++ b/flask/config.py @@ -93,9 +93,9 @@ class Config(dict): app.config.from_pyfile(os.environ['YOURAPPLICATION_SETTINGS']) :param variable_name: name of the environment variable - :param silent: set to `True` if you want silent failure for missing + :param silent: set to ``True`` if you want silent failure for missing files. - :return: bool. `True` if able to load config, `False` otherwise. + :return: bool. ``True`` if able to load config, ``False`` otherwise. """ rv = os.environ.get(variable_name) if not rv: @@ -116,7 +116,7 @@ class Config(dict): :param filename: the filename of the config. This can either be an absolute filename or a filename relative to the root path. - :param silent: set to `True` if you want silent failure for missing + :param silent: set to ``True`` if you want silent failure for missing files. .. versionadded:: 0.7 @@ -173,7 +173,7 @@ class Config(dict): :param filename: the filename of the JSON file. This can either be an absolute filename or a filename relative to the root path. - :param silent: set to `True` if you want silent failure for missing + :param silent: set to ``True`` if you want silent failure for missing files. .. versionadded:: 1.0 diff --git a/flask/ctx.py b/flask/ctx.py index d79ad00d..b8285112 100644 --- a/flask/ctx.py +++ b/flask/ctx.py @@ -210,7 +210,7 @@ class RequestContext(object): exceptions happen so that interactive debuggers have a chance to introspect the data. With 0.4 this can also be forced for requests that did not fail and outside of `DEBUG` mode. By setting - ``'flask._preserve_context'`` to `True` on the WSGI environment the + ``'flask._preserve_context'`` to ``True`` on the WSGI environment the context will not pop itself at the end of the request. This is used by the :meth:`~flask.Flask.test_client` for example to implement the deferred cleanup functionality. diff --git a/flask/helpers.py b/flask/helpers.py index aaed81c4..828e8f67 100644 --- a/flask/helpers.py +++ b/flask/helpers.py @@ -188,7 +188,7 @@ def url_for(endpoint, **values): Variable arguments that are unknown to the target endpoint are appended to the generated URL as query arguments. If the value of a query argument - is `None`, the whole pair is skipped. In case blueprints are active + is ``None``, the whole pair is skipped. In case blueprints are active you can shortcut references to the same blueprint by prefixing the local endpoint with a dot (``.``). @@ -203,7 +203,7 @@ def url_for(endpoint, **values): function results in a :exc:`~werkzeug.routing.BuildError` when the current app does not have a URL for the given endpoint and values. When it does, the :data:`~flask.current_app` calls its :attr:`~Flask.url_build_error_handlers` if - it is not `None`, which can return a string to use as the result of + it is not ``None``, which can return a string to use as the result of `url_for` (instead of `url_for`'s default to raise the :exc:`~werkzeug.routing.BuildError` exception) or re-raise the exception. An example:: @@ -244,11 +244,11 @@ def url_for(endpoint, **values): :param endpoint: the endpoint of the URL (name of the function) :param values: the variable arguments of the URL rule - :param _external: if set to `True`, an absolute URL is generated. Server + :param _external: if set to ``True``, an absolute URL is generated. Server address can be changed via `SERVER_NAME` configuration variable which defaults to `localhost`. :param _scheme: a string specifying the desired URL scheme. The `_external` - parameter must be set to `True` or a `ValueError` is raised. The default + parameter must be set to ``True`` or a `ValueError` is raised. The default behavior uses the same scheme as the current request, or ``PREFERRED_URL_SCHEME`` from the :ref:`app configuration ` if no request context is available. As of Werkzeug 0.10, this also can be set @@ -376,7 +376,7 @@ def get_flashed_messages(with_categories=False, category_filter=[]): """Pulls all flashed messages from the session and returns them. Further calls in the same request to the function will return the same messages. By default just the messages are returned, - but when `with_categories` is set to `True`, the return value will + but when `with_categories` is set to ``True``, the return value will be a list of tuples in the form ``(category, message)`` instead. Filter the flashed messages to one or more categories by providing those @@ -385,7 +385,7 @@ def get_flashed_messages(with_categories=False, category_filter=[]): arguments are distinct: * `with_categories` controls whether categories are returned with message - text (`True` gives a tuple, where `False` gives just the message text). + text (``True`` gives a tuple, where ``False`` gives just the message text). * `category_filter` filters the messages down to only those matching the provided categories. @@ -397,7 +397,7 @@ def get_flashed_messages(with_categories=False, category_filter=[]): .. versionchanged:: 0.9 `category_filter` parameter added. - :param with_categories: set to `True` to also receive categories. + :param with_categories: set to ``True`` to also receive categories. :param category_filter: whitelist of categories to limit return values """ flashes = _request_ctx_stack.top.flashes @@ -459,14 +459,14 @@ def send_file(filename_or_fp, mimetype=None, as_attachment=False, of data to send before calling :func:`send_file`. :param mimetype: the mimetype of the file if provided, otherwise auto detection happens. - :param as_attachment: set to `True` if you want to send this file with + :param as_attachment: set to ``True`` if you want to send this file with a ``Content-Disposition: attachment`` header. :param attachment_filename: the filename for the attachment if it differs from the file's filename. - :param add_etags: set to `False` to disable attaching of etags. - :param conditional: set to `True` to enable conditional responses. + :param add_etags: set to ``False`` to disable attaching of etags. + :param conditional: set to ``True`` to enable conditional responses. - :param cache_timeout: the timeout in seconds for the headers. When `None` + :param cache_timeout: the timeout in seconds for the headers. When ``None`` (default), this value is set by :meth:`~Flask.get_send_file_max_age` of :data:`~flask.current_app`. @@ -784,7 +784,7 @@ class _PackageBoundObject(object): #: it was set by the constructor. self.import_name = import_name - #: location of the templates. `None` if templates should not be + #: location of the templates. ``None`` if templates should not be #: exposed. self.template_folder = template_folder @@ -818,7 +818,7 @@ class _PackageBoundObject(object): @property def has_static_folder(self): - """This is `True` if the package bound object's container has a + """This is ``True`` if the package bound object's container has a folder named ``'static'``. .. versionadded:: 0.5 @@ -843,7 +843,7 @@ class _PackageBoundObject(object): Static file functions such as :func:`send_from_directory` use this function, and :func:`send_file` calls this function on - :data:`~flask.current_app` when the given cache_timeout is `None`. If a + :data:`~flask.current_app` when the given cache_timeout is ``None``. If a cache_timeout is given in :func:`send_file`, that timeout is used; otherwise, this method is called. diff --git a/flask/sessions.py b/flask/sessions.py index 2bf455f4..46f42ba7 100644 --- a/flask/sessions.py +++ b/flask/sessions.py @@ -42,13 +42,13 @@ class SessionMixin(object): #: some session backends can tell you if a session is new, but that is #: not necessarily guaranteed. Use with caution. The default mixin - #: implementation just hardcodes `False` in. + #: implementation just hardcodes ``False`` in. new = False - #: for some backends this will always be `True`, but some backends will + #: for some backends this will always be ``True``, but some backends will #: default this to false and detect changes in the dictionary for as #: long as changes do not happen on mutable structures in the session. - #: The default mixin implementation just hardcodes `True` in. + #: The default mixin implementation just hardcodes ``True`` in. modified = True @@ -149,7 +149,7 @@ class SessionInterface(object): class Session(dict, SessionMixin): pass - If :meth:`open_session` returns `None` Flask will call into + If :meth:`open_session` returns ``None`` Flask will call into :meth:`make_null_session` to create a session that acts as replacement if the session support cannot work because some requirement is not fulfilled. The default :class:`NullSession` class that is created @@ -228,7 +228,7 @@ class SessionInterface(object): """Returns the path for which the cookie should be valid. The default implementation uses the value from the ``SESSION_COOKIE_PATH`` config var if it's set, and falls back to ``APPLICATION_ROOT`` or - uses ``/`` if it's `None`. + uses ``/`` if it's ``None``. """ return app.config['SESSION_COOKIE_PATH'] or \ app.config['APPLICATION_ROOT'] or '/' @@ -248,7 +248,7 @@ class SessionInterface(object): def get_expiration_time(self, app, session): """A helper method that returns an expiration date for the session - or `None` if the session is linked to the browser session. The + or ``None`` if the session is linked to the browser session. The default implementation returns now + the permanent session lifetime configured on the application. """ @@ -260,8 +260,8 @@ class SessionInterface(object): used by session backends to figure out if they should emit a set-cookie header or not. The default behavior is controlled by the ``SESSION_REFRESH_EACH_REQUEST`` config variable. If - it's set to `False` then a cookie is only set if the session is - modified, if set to `True` it's always set if the session is + it's set to ``False`` then a cookie is only set if the session is + modified, if set to ``True`` it's always set if the session is permanent. This check is usually skipped if sessions get deleted. @@ -274,7 +274,7 @@ class SessionInterface(object): return save_each and session.permanent def open_session(self, app, request): - """This method has to be implemented and must either return `None` + """This method has to be implemented and must either return ``None`` in case the loading failed because of a configuration error or an instance of a session object which implements a dictionary like interface + the methods and attributes on :class:`SessionMixin`. diff --git a/flask/wrappers.py b/flask/wrappers.py index 81c39f18..e8d77b21 100644 --- a/flask/wrappers.py +++ b/flask/wrappers.py @@ -47,7 +47,7 @@ class Request(RequestBase): url_rule = None #: A dict of view arguments that matched the request. If an exception - #: happened when matching, this will be `None`. + #: happened when matching, this will be ``None``. view_args = None #: If matching the URL failed, this is the exception that will be @@ -72,7 +72,7 @@ class Request(RequestBase): """The endpoint that matched the request. This in combination with :attr:`view_args` can be used to reconstruct the same or a modified URL. If an exception happened when matching, this will - be `None`. + be ``None``. """ if self.url_rule is not None: return self.url_rule.endpoint @@ -99,7 +99,7 @@ class Request(RequestBase): @property def json(self): """If the mimetype is `application/json` this will contain the - parsed JSON data. Otherwise this will be `None`. + parsed JSON data. Otherwise this will be ``None``. The :meth:`get_json` method should be used instead. """ @@ -130,10 +130,10 @@ class Request(RequestBase): only load the json data if the mimetype is ``application/json`` but this can be overridden by the `force` parameter. - :param force: if set to `True` the mimetype is ignored. - :param silent: if set to `True` this method will fail silently - and return `None`. - :param cache: if set to `True` the parsed JSON data is remembered + :param force: if set to ``True`` the mimetype is ignored. + :param silent: if set to ``True`` this method will fail silently + and return ``None``. + :param cache: if set to ``True`` the parsed JSON data is remembered on the request. """ rv = getattr(self, '_cached_json', _missing)