From 3fa4fd0908fcd2300b568171a285726d19a976e1 Mon Sep 17 00:00:00 2001 From: defuz Date: Wed, 5 Nov 2014 06:13:01 +0300 Subject: [PATCH] docs: http method names like ``GET`` and ``POST`` --- CHANGES | 4 ++-- docs/api.rst | 16 ++++++++-------- docs/patterns/jquery.rst | 2 +- docs/patterns/wtforms.rst | 4 ++-- docs/quickstart.rst | 30 +++++++++++++++--------------- docs/security.rst | 4 ++-- docs/testing.rst | 2 +- docs/tutorial/templates.rst | 2 +- docs/tutorial/views.rst | 2 +- docs/views.rst | 2 +- flask/app.py | 20 ++++++++++---------- 11 files changed, 44 insertions(+), 44 deletions(-) diff --git a/CHANGES b/CHANGES index c5eb7bbc..8fdf56cf 100644 --- a/CHANGES +++ b/CHANGES @@ -326,7 +326,7 @@ Released on June 28th 2011, codename Grappa - Added :meth:`~flask.Flask.make_default_options_response` which can be used by subclasses to alter the default - behavior for `OPTIONS` responses. + behavior for ``OPTIONS`` responses. - Unbound locals now raise a proper :exc:`RuntimeError` instead of an :exc:`AttributeError`. - Mimetype guessing and etag support based on file objects is now @@ -379,7 +379,7 @@ Version 0.6.1 Bugfix release, released on December 31st 2010 -- Fixed an issue where the default `OPTIONS` response was +- Fixed an issue where the default ``OPTIONS`` response was not exposing all valid methods in the `Allow` header. - Jinja2 template loading syntax now allows "./" in front of a template load path. Previously this caused issues with diff --git a/docs/api.rst b/docs/api.rst index 558fd704..0306c566 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -33,8 +33,8 @@ Incoming Request Data .. attribute:: form - A :class:`~werkzeug.datastructures.MultiDict` with the parsed form data from `POST` - or `PUT` requests. Please keep in mind that file uploads will not + A :class:`~werkzeug.datastructures.MultiDict` with the parsed form data from ``POST`` + or ``PUT`` requests. Please keep in mind that file uploads will not end up here, but instead in the :attr:`files` attribute. .. attribute:: args @@ -71,7 +71,7 @@ Incoming Request Data .. attribute:: files A :class:`~werkzeug.datastructures.MultiDict` with files uploaded as part of a - `POST` or `PUT` request. Each file is stored as + ``POST`` or ``PUT`` request. Each file is stored as :class:`~werkzeug.datastructures.FileStorage` object. It basically behaves like a standard file object you know from Python, with the difference that it also has a :meth:`~werkzeug.datastructures.FileStorage.save` function that can @@ -704,9 +704,9 @@ instead of the `view_func` parameter. `**options` the options to be forwarded to the underlying :class:`~werkzeug.routing.Rule` object. A change to Werkzeug is handling of method options. methods is a list - of methods this rule should be limited to (`GET`, `POST` - etc.). By default a rule just listens for `GET` (and - implicitly `HEAD`). Starting with Flask 0.6, `OPTIONS` is + of methods this rule should be limited to (``GET``, ``POST`` + etc.). By default a rule just listens for ``GET`` (and + implicitly ``HEAD``). Starting with Flask 0.6, ``OPTIONS`` is implicitly added and handled by the standard request handling. They have to be specified as keyword arguments. =============== ========================================================== @@ -733,8 +733,8 @@ some defaults to :meth:`~flask.Flask.add_url_rule` or general behavior: - `provide_automatic_options`: if this attribute is set Flask will either force enable or disable the automatic implementation of the - HTTP `OPTIONS` response. This can be useful when working with - decorators that want to customize the `OPTIONS` response on a per-view + HTTP ``OPTIONS`` response. This can be useful when working with + decorators that want to customize the ``OPTIONS`` response on a per-view basis. - `required_methods`: if this attribute is set, Flask will always add diff --git a/docs/patterns/jquery.rst b/docs/patterns/jquery.rst index 913bcedf..3ac1412d 100644 --- a/docs/patterns/jquery.rst +++ b/docs/patterns/jquery.rst @@ -156,7 +156,7 @@ explanation of the little bit of code above: when the user clicked on the element. If that function returns `false`, the default behavior will not kick in (in this case, navigate to the `#` URL). -4. ``$.getJSON(url, data, func)`` sends a `GET` request to `url` and will +4. ``$.getJSON(url, data, func)`` sends a ``GET`` request to `url` and will send the contents of the `data` object as query parameters. Once the data arrived, it will call the given function with the return value as argument. Note that we can use the `$SCRIPT_ROOT` variable here that diff --git a/docs/patterns/wtforms.rst b/docs/patterns/wtforms.rst index 49c1ca72..0e41d594 100644 --- a/docs/patterns/wtforms.rst +++ b/docs/patterns/wtforms.rst @@ -61,8 +61,8 @@ the code as necessary. Things to remember: 1. create the form from the request :attr:`~flask.request.form` value if - the data is submitted via the HTTP `POST` method and - :attr:`~flask.request.args` if the data is submitted as `GET`. + 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`` otherwise. diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 14753b59..d032b3c6 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -292,7 +292,7 @@ HTTP Methods ```````````` HTTP (the protocol web applications are speaking) knows different methods for -accessing URLs. By default, a route only answers to `GET` requests, but that +accessing URLs. By default, a route only answers to ``GET`` requests, but that can be changed by providing the `methods` argument to the :meth:`~flask.Flask.route` decorator. Here are some examples:: @@ -305,11 +305,11 @@ can be changed by providing the `methods` argument to the else: show_the_login_form() -If `GET` is present, `HEAD` will be added automatically for you. You -don't have to deal with that. It will also make sure that `HEAD` requests +If ``GET`` is present, ``HEAD`` will be added automatically for you. You +don't have to deal with that. It will also make sure that ``HEAD`` requests are handled as the `HTTP RFC`_ (the document describing the HTTP protocol) demands, so you can completely ignore that part of the HTTP -specification. Likewise, as of Flask 0.6, `OPTIONS` is implemented for you +specification. Likewise, as of Flask 0.6, ``OPTIONS`` is implemented for you automatically as well. You have no idea what an HTTP method is? Worry not, here is a quick @@ -319,44 +319,44 @@ The HTTP method (also often called "the verb") tells the server what the clients wants to *do* with the requested page. The following methods are very common: -`GET` +``GET`` The browser tells the server to just *get* the information stored on that page and send it. This is probably the most common method. -`HEAD` +``HEAD`` The browser tells the server to get the information, but it is only interested in the *headers*, not the content of the page. An - application is supposed to handle that as if a `GET` request was + application is supposed to handle that as if a ``GET`` request was received but to not deliver the actual content. In Flask you don't have to deal with that at all, the underlying Werkzeug library handles that for you. -`POST` +``POST`` The browser tells the server that it wants to *post* some new information to that URL and that the server must ensure the data is stored and only stored once. This is how HTML forms usually transmit data to the server. -`PUT` - Similar to `POST` but the server might trigger the store procedure +``PUT`` + Similar to ``POST`` but the server might trigger the store procedure multiple times by overwriting the old values more than once. Now you might be asking why this is useful, but there are some good reasons to do it this way. Consider that the connection is lost during transmission: in this situation a system between the browser and the server might receive the request safely a second time without breaking - things. With `POST` that would not be possible because it must only + things. With ``POST`` that would not be possible because it must only be triggered once. -`DELETE` +``DELETE`` Remove the information at the given location. -`OPTIONS` +``OPTIONS`` Provides a quick way for a client to figure out which methods are supported by this URL. Starting with Flask 0.6, this is implemented for you automatically. Now the interesting part is that in HTML4 and XHTML1, the only methods a -form can submit to the server are `GET` and `POST`. But with JavaScript +form can submit to the server are ``GET`` and ``POST``. But with JavaScript and future HTML standards you can use the other methods as well. Furthermore HTTP has become quite popular lately and browsers are no longer the only clients that are using HTTP. For instance, many revision control systems @@ -541,7 +541,7 @@ the `flask` module:: The current request method is available by using the :attr:`~flask.request.method` attribute. To access form data (data -transmitted in a `POST` or `PUT` request) you can use the +transmitted in a ``POST`` or ``PUT`` request) you can use the :attr:`~flask.request.form` attribute. Here is a full example of the two attributes mentioned above:: diff --git a/docs/security.rst b/docs/security.rst index 909ef537..e5703274 100644 --- a/docs/security.rst +++ b/docs/security.rst @@ -70,7 +70,7 @@ don't keep that in mind, some people might be able to trick your application's users with social engineering to do stupid things without them knowing. -Say you have a specific URL that, when you sent `POST` requests to will +Say you have a specific URL that, when you sent ``POST`` requests to will delete a user's profile (say `http://example.com/user/delete`). If an attacker now creates a page that sends a post request to that page with some JavaScript they just has to trick some users to load that page and @@ -130,7 +130,7 @@ Not very uncommon: ] And it is doing that of course only as long as you are logged in and only -for you. And it is doing that for all `GET` requests to a certain URL, +for you. And it is doing that for all ``GET`` requests to a certain URL, say the URL for that request is ``http://example.com/api/get_friends.json``. diff --git a/docs/testing.rst b/docs/testing.rst index de5c9143..650a2758 100644 --- a/docs/testing.rst +++ b/docs/testing.rst @@ -112,7 +112,7 @@ test method to our class, like this:: Notice that our test functions begin with the word `test`; this allows :mod:`unittest` to automatically identify the method as a test to run. -By using `self.app.get` we can send an HTTP `GET` request to the application with +By using `self.app.get` we can send an HTTP ``GET`` request to the application with the given path. The return value will be a :class:`~flask.Flask.response_class` object. We can now use the :attr:`~werkzeug.wrappers.BaseResponse.data` attribute to inspect the return value (as string) from the application. In this case, we ensure that diff --git a/docs/tutorial/templates.rst b/docs/tutorial/templates.rst index e7597b4b..63c0a386 100644 --- a/docs/tutorial/templates.rst +++ b/docs/tutorial/templates.rst @@ -58,7 +58,7 @@ show_entries.html This template extends the `layout.html` template from above to display the messages. Note that the `for` loop iterates over the messages we passed in with the :func:`~flask.render_template` function. We also tell the -form to submit to your `add_entry` function and use `POST` as HTTP +form to submit to your `add_entry` function and use ``POST`` as HTTP method: .. sourcecode:: html+jinja diff --git a/docs/tutorial/views.rst b/docs/tutorial/views.rst index 35c8a2c8..8d34bce4 100644 --- a/docs/tutorial/views.rst +++ b/docs/tutorial/views.rst @@ -29,7 +29,7 @@ Add New Entry ------------- This view lets the user add new entries if they are logged in. This only -responds to `POST` requests, the actual form is shown on the +responds to ``POST`` requests, the actual form is shown on the `show_entries` page. If everything worked out well we will :func:`~flask.flash` an information message to the next request and redirect back to the `show_entries` page:: diff --git a/docs/views.rst b/docs/views.rst index 210d8f18..cc72febb 100644 --- a/docs/views.rst +++ b/docs/views.rst @@ -46,7 +46,7 @@ class into an actual view function by using the that function is the name of the endpoint that view will then have. But this by itself is not helpful, so let's refactor the code a bit:: - + from flask.views import View class ListView(View): diff --git a/flask/app.py b/flask/app.py index 4d7911a6..19d84c6a 100644 --- a/flask/app.py +++ b/flask/app.py @@ -968,7 +968,7 @@ class Flask(_PackageBoundObject): `view_func` parameter added. .. versionchanged:: 0.6 - `OPTIONS` is added automatically as method. + ``OPTIONS`` is added automatically as method. :param rule: the URL rule as string :param endpoint: the endpoint for the registered URL rule. Flask @@ -980,9 +980,9 @@ class Flask(_PackageBoundObject): :class:`~werkzeug.routing.Rule` object. A change to Werkzeug is handling of method options. methods is a list of methods this rule should be limited - to (`GET`, `POST` etc.). By default a rule - just listens for `GET` (and implicitly `HEAD`). - Starting with Flask 0.6, `OPTIONS` is implicitly + to (``GET``, ``POST`` etc.). By default a rule + just listens for ``GET`` (and implicitly ``HEAD``). + Starting with Flask 0.6, ``OPTIONS`` is implicitly added and handled by the standard request handling. """ if endpoint is None: @@ -992,7 +992,7 @@ class Flask(_PackageBoundObject): # if the methods are not given and the view_func object knows its # methods we can use that instead. If neither exists, we go with - # a tuple of only `GET` as default. + # a tuple of only ``GET`` as default. if methods is None: methods = getattr(view_func, 'methods', None) or ('GET',) if isinstance(methods, string_types): @@ -1048,9 +1048,9 @@ class Flask(_PackageBoundObject): :class:`~werkzeug.routing.Rule` object. A change to Werkzeug is handling of method options. methods is a list of methods this rule should be limited - to (`GET`, `POST` etc.). By default a rule - just listens for `GET` (and implicitly `HEAD`). - Starting with Flask 0.6, `OPTIONS` is implicitly + to (``GET``, ``POST`` etc.). By default a rule + just listens for ``GET`` (and implicitly ``HEAD``). + Starting with Flask 0.6, ``OPTIONS`` is implicitly added and handled by the standard request handling. """ def decorator(f): @@ -1559,9 +1559,9 @@ class Flask(_PackageBoundObject): self._got_first_request = True def make_default_options_response(self): - """This method is called to create the default `OPTIONS` response. + """This method is called to create the default ``OPTIONS`` response. This can be changed through subclassing to change the default - behavior of `OPTIONS` responses. + behavior of ``OPTIONS`` responses. .. versionadded:: 0.7 """