PKG-INFO 23 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612
  1. Metadata-Version: 1.2
  2. Name: django-cors-headers
  3. Version: 2.5.3
  4. Summary: django-cors-headers is a Django application for handling the server headers required for Cross-Origin Resource Sharing (CORS).
  5. Home-page: https://github.com/ottoyiu/django-cors-headers
  6. Author: Otto Yiu
  7. Author-email: otto@live.ca
  8. License: MIT License
  9. Description: django-cors-headers
  10. ===================
  11. A Django App that adds CORS (Cross-Origin Resource Sharing) headers to
  12. responses.
  13. Although JSON-P is useful, it is strictly limited to GET requests. CORS
  14. builds on top of ``XmlHttpRequest`` to allow developers to make cross-domain
  15. requests, similar to same-domain requests. Read more about it here:
  16. http://www.html5rocks.com/en/tutorials/cors/
  17. .. image:: https://travis-ci.org/ottoyiu/django-cors-headers.svg?branch=master
  18. :target: https://travis-ci.org/ottoyiu/django-cors-headers
  19. Requirements
  20. ------------
  21. Tested with all combinations of:
  22. * Python: 2.7, 3.5, 3.6, 3.7
  23. * Django: 1.11, 2.0, 2.1, 2.2
  24. Setup
  25. -----
  26. Install from **pip**:
  27. .. code-block:: sh
  28. pip install django-cors-headers
  29. and then add it to your installed apps:
  30. .. code-block:: python
  31. INSTALLED_APPS = (
  32. ...
  33. 'corsheaders',
  34. ...
  35. )
  36. You will also need to add a middleware class to listen in on responses:
  37. .. code-block:: python
  38. MIDDLEWARE = [ # Or MIDDLEWARE_CLASSES on Django < 1.10
  39. ...
  40. 'corsheaders.middleware.CorsMiddleware',
  41. 'django.middleware.common.CommonMiddleware',
  42. ...
  43. ]
  44. ``CorsMiddleware`` should be placed as high as possible, especially before any
  45. middleware that can generate responses such as Django's ``CommonMiddleware`` or
  46. Whitenoise's ``WhiteNoiseMiddleware``. If it is not before, it will not be able
  47. to add the CORS headers to these responses.
  48. Also if you are using ``CORS_REPLACE_HTTPS_REFERER`` it should be placed before
  49. Django's ``CsrfViewMiddleware`` (see more below).
  50. About
  51. -----
  52. **django-cors-headers** was created in January 2013 by Otto Yiu. It went
  53. unmaintained from August 2015 and was forked in January 2016 to the package
  54. `django-cors-middleware <https://github.com/zestedesavoir/django-cors-middleware>`_
  55. by Laville Augustin at Zeste de Savoir.
  56. In September 2016, Adam Johnson, Ed Morley, and others gained maintenance
  57. responsibility for **django-cors-headers**
  58. (`Issue 110 <https://github.com/ottoyiu/django-cors-headers/issues/110>`_) from
  59. Otto Yiu.
  60. Basically all of the changes in the forked **django-cors-middleware** were
  61. merged back, or re-implemented in a different way, so it should be possible to
  62. switch back. If there's a feature that hasn't been merged, please open an issue
  63. about it.
  64. **django-cors-headers** has had `40+
  65. contributors <https://github.com/ottoyiu/django-cors-headers/graphs/contributors>`_
  66. in its time; thanks to every one of them.
  67. Configuration
  68. -------------
  69. Configure the middleware's behaviour in your Django settings. You must add the
  70. hosts that are allowed to do cross-site requests to
  71. ``CORS_ORIGIN_WHITELIST``, or set ``CORS_ORIGIN_ALLOW_ALL`` to ``True``
  72. to allow all hosts.
  73. ``CORS_ORIGIN_ALLOW_ALL``
  74. ~~~~~~~~~~~~~~~~~~~~~~~~~
  75. If ``True``, the whitelist will not be used and all origins will be accepted.
  76. Defaults to ``False``.
  77. ``CORS_ORIGIN_WHITELIST``
  78. ~~~~~~~~~~~~~~~~~~~~~~~~~
  79. A list of origin hostnames that are authorized to make cross-site HTTP
  80. requests. The value ``'null'`` can also appear in this list, and will match the
  81. ``Origin: null`` header that is used in `"privacy-sensitive contexts"
  82. <https://tools.ietf.org/html/rfc6454#section-6>`_, such as when the client is
  83. running from a ``file://`` domain. Defaults to ``[]``.
  84. Example:
  85. .. code-block:: python
  86. CORS_ORIGIN_WHITELIST = (
  87. 'google.com',
  88. 'hostname.example.com',
  89. 'localhost:8000',
  90. '127.0.0.1:9000'
  91. )
  92. ``CORS_ORIGIN_REGEX_WHITELIST``
  93. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  94. A list of regexes that match origin regex list of origin hostnames that are
  95. authorized to make cross-site HTTP requests. Defaults to ``[]``. Useful when
  96. ``CORS_ORIGIN_WHITELIST`` is impractical, such as when you have a large
  97. number of subdomains.
  98. Example:
  99. .. code-block:: python
  100. CORS_ORIGIN_REGEX_WHITELIST = (r'^(https?://)?(\w+\.)?google\.com$', )
  101. --------------
  102. The following are optional settings, for which the defaults probably suffice.
  103. ``CORS_URLS_REGEX``
  104. ~~~~~~~~~~~~~~~~~~~
  105. A regex which restricts the URL's for which the CORS headers will be sent.
  106. Defaults to ``r'^.*$'``, i.e. match all URL's. Useful when you only need CORS
  107. on a part of your site, e.g. an API at ``/api/``.
  108. Example:
  109. .. code-block:: python
  110. CORS_URLS_REGEX = r'^/api/.*$'
  111. ``CORS_ALLOW_METHODS``
  112. ~~~~~~~~~~~~~~~~~~~~~~
  113. A list of HTTP verbs that are allowed for the actual request. Defaults to:
  114. .. code-block:: python
  115. CORS_ALLOW_METHODS = (
  116. 'DELETE',
  117. 'GET',
  118. 'OPTIONS',
  119. 'PATCH',
  120. 'POST',
  121. 'PUT',
  122. )
  123. The default can be imported as ``corsheaders.defaults.default_methods`` so you
  124. can just extend it with your custom methods. This allows you to keep up to date
  125. with any future changes. For example:
  126. .. code-block:: python
  127. from corsheaders.defaults import default_methods
  128. CORS_ALLOW_METHODS = default_methods + (
  129. 'POKE',
  130. )
  131. ``CORS_ALLOW_HEADERS``
  132. ~~~~~~~~~~~~~~~~~~~~~~
  133. The list of non-standard HTTP headers that can be used when making the actual
  134. request. Defaults to:
  135. .. code-block:: python
  136. CORS_ALLOW_HEADERS = (
  137. 'accept',
  138. 'accept-encoding',
  139. 'authorization',
  140. 'content-type',
  141. 'dnt',
  142. 'origin',
  143. 'user-agent',
  144. 'x-csrftoken',
  145. 'x-requested-with',
  146. )
  147. The default can be imported as ``corsheaders.defaults.default_headers`` so you
  148. can extend it with your custom headers. This allows you to keep up to date with
  149. any future changes. For example:
  150. .. code-block:: python
  151. from corsheaders.defaults import default_headers
  152. CORS_ALLOW_HEADERS = default_headers + (
  153. 'my-custom-header',
  154. )
  155. ``CORS_EXPOSE_HEADERS``
  156. ~~~~~~~~~~~~~~~~~~~~~~~
  157. The list of HTTP headers that are to be exposed to the browser. Defaults to
  158. ``[]``.
  159. ``CORS_PREFLIGHT_MAX_AGE``
  160. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  161. The number of seconds a client/browser can cache the preflight response. If
  162. this is 0 (or any falsey value), no max age header will be sent. Defaults to
  163. ``86400`` (one day).
  164. **Note:** A preflight request is an extra request that is made when making a
  165. "not-so-simple" request (e.g. ``Content-Type`` is not
  166. ``application/x-www-form-urlencoded``) to determine what requests the server
  167. actually accepts. Read more about it in the `HTML 5 Rocks CORS tutorial
  168. <https://www.html5rocks.com/en/tutorials/cors/>`_.
  169. ``CORS_ALLOW_CREDENTIALS``
  170. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  171. If ``True``, cookies will be allowed to be included in cross-site HTTP
  172. requests. Defaults to ``False``.
  173. Note: in Django 2.1 the `SESSION_COOKIE_SAMESITE`_ setting was added, set to
  174. ``'Lax'`` by default, which will prevent Django's session cookie being sent
  175. cross-domain. Change it to ``None`` to bypass this security restriction.
  176. .. _SESSION_COOKIE_SAMESITE: https://docs.djangoproject.com/en/2.1/ref/settings/#std:setting-SESSION_COOKIE_SAMESITE
  177. ``CORS_MODEL``
  178. ~~~~~~~~~~~~~~
  179. If set, this should be the path to a model to look up allowed origins, in the
  180. form ``app.modelname``. Defaults to ``None``.
  181. The model should inherit from ``corsheaders.models.AbstractCorsModel`` and specify
  182. the allowed origin in the ``CharField`` called ``cors``.
  183. CSRF Integration
  184. ----------------
  185. Most sites will need to take advantage of the `Cross-Site Request Forgery
  186. protection <https://docs.djangoproject.com/en/dev/ref/csrf/>`_ that Django
  187. offers. CORS and CSRF are separate, and Django has no way of using your CORS
  188. configuration to exempt sites from the ``Referer`` checking that it does on
  189. secure requests. The way to do that is with its `CSRF_TRUSTED_ORIGINS setting
  190. <https://docs.djangoproject.com/en/dev/ref/settings/#csrf-trusted-origins>`_.
  191. For example:
  192. .. code-block:: python
  193. CORS_ORIGIN_WHITELIST = (
  194. 'read.only.com',
  195. 'change.allowed.com',
  196. )
  197. CSRF_TRUSTED_ORIGINS = (
  198. 'change.allowed.com',
  199. )
  200. ``CORS_REPLACE_HTTPS_REFERER``
  201. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  202. ``CSRF_TRUSTED_ORIGINS`` was introduced in Django 1.9, so users of earlier
  203. versions will need an alternate solution. If ``CORS_REPLACE_HTTPS_REFERER`` is
  204. ``True``, ``CorsMiddleware`` will change the ``Referer`` header to something
  205. that will pass Django's CSRF checks whenever the CORS checks pass. Defaults to
  206. ``False``.
  207. Note that unlike ``CSRF_TRUSTED_ORIGINS``, this setting does not allow you to
  208. distinguish between domains that are trusted to *read* resources by CORS and
  209. domains that are trusted to *change* resources by avoiding CSRF protection.
  210. With this feature enabled you should also add
  211. ``corsheaders.middleware.CorsPostCsrfMiddleware`` after
  212. ``django.middleware.csrf.CsrfViewMiddleware`` in your ``MIDDLEWARE_CLASSES`` to
  213. undo the ``Referer`` replacement:
  214. .. code-block:: python
  215. MIDDLEWARE_CLASSES = [
  216. ...
  217. 'corsheaders.middleware.CorsMiddleware',
  218. ...
  219. 'django.middleware.csrf.CsrfViewMiddleware',
  220. 'corsheaders.middleware.CorsPostCsrfMiddleware',
  221. ...
  222. ]
  223. Signals
  224. -------
  225. If you have a use case that requires more than just the above configuration,
  226. you can attach code to check if a given request should be allowed. For example,
  227. this can be used to read the list of origins you allow from a model. Attach any
  228. number of handlers to the ``check_request_enabled``
  229. `Django signal <https://docs.djangoproject.com/en/1.10/ref/signals/>`_, which
  230. provides the ``request`` argument (use ``**kwargs`` in your handler to protect
  231. against any future arguments being added). If any handler attached to the
  232. signal returns a truthy value, the request will be allowed.
  233. For example you might define a handler like this:
  234. .. code-block:: python
  235. # myapp/handlers.py
  236. from corsheaders.signals import check_request_enabled
  237. from .models import MySite
  238. def cors_allow_mysites(sender, request, **kwargs):
  239. return MySite.objects.filter(host=request.host).exists()
  240. check_request_enabled.connect(cors_allow_mysites)
  241. Then connect it at app ready time using a `Django AppConfig
  242. <https://docs.djangoproject.com/en/1.10/ref/applications/>`_:
  243. .. code-block:: python
  244. # myapp/__init__.py
  245. default_app_config = 'myapp.apps.MyAppConfig'
  246. .. code-block:: python
  247. # myapp/apps.py
  248. from django.apps import AppConfig
  249. class MyAppConfig(AppConfig):
  250. name = 'myapp'
  251. def ready(self):
  252. # Makes sure all signal handlers are connected
  253. from . import handlers # noqa
  254. A common use case for the signal is to allow *all* origins to access a subset
  255. of URL's, whilst allowing a normal set of origins to access *all* URL's. This
  256. isn't possible using just the normal configuration, but it can be achieved with
  257. a signal handler.
  258. First set ``CORS_ORIGIN_WHITELIST`` to the list of trusted origins that are
  259. allowed to access every URL, and then add a handler to
  260. ``check_request_enabled`` to allow CORS regardless of the origin for the
  261. unrestricted URL's. For example:
  262. .. code-block:: python
  263. # myapp/handlers.py
  264. from corsheaders.signals import check_request_enabled
  265. def cors_allow_api_to_everyone(sender, request, **kwargs):
  266. return request.path.startswith('/api/')
  267. check_request_enabled.connect(cors_allow_api_to_everyone)
  268. History
  269. =======
  270. Pending
  271. -------
  272. .. Insert new release notes below this line
  273. 2.5.3 (2019-04-28)
  274. ------------------
  275. * Tested on Django 2.2. No changes were needed for compatibility.
  276. * Tested on Python 3.7. No changes were needed for compatibility.
  277. 2.5.2 (2019-03-15)
  278. ------------------
  279. * Improve inclusion of tests in ``sdist`` to ignore ``.pyc`` files.
  280. 2.5.1 (2019-03-13)
  281. ------------------
  282. * Include test infrastructure in ``sdist`` to allow consumers to use it.
  283. 2.5.0 (2019-03-05)
  284. ------------------
  285. * Drop Django 1.8, 1.9, and 1.10 support. Only Django 1.11+ is supported now.
  286. 2.4.1 (2019-02-28)
  287. ------------------
  288. * Fix ``DeprecationWarning`` from importing ``collections.abc.Sequence`` on
  289. Python 3.7.
  290. 2.4.0 (2018-07-18)
  291. ------------------
  292. * Always add 'Origin' to the 'Vary' header for responses to enabled URL's,
  293. to prevent caching of responses intended for one origin being served for
  294. another.
  295. 2.3.0 (2018-06-27)
  296. ------------------
  297. * Match ``CORS_URLS_REGEX`` to ``request.path_info`` instead of
  298. ``request.path``, so the patterns can work without knowing the site's path
  299. prefix at configuration time.
  300. 2.2.1 (2018-06-27)
  301. ------------------
  302. * Add ``Content-Length`` header to CORS preflight requests. This fixes issues
  303. with some HTTP proxies and servers, e.g. AWS Elastic Beanstalk.
  304. 2.2.0 (2018-02-28)
  305. ------------------
  306. * Django 2.0 compatibility. Again there were no changes to the actual library
  307. code, so previous versions probably work.
  308. * Ensured that ``request._cors_enabled`` is always a ``bool()`` - previously it
  309. could be set to a regex match object.
  310. 2.1.0 (2017-05-28)
  311. ------------------
  312. * Django 1.11 compatibility. There were no changes to the actual library code,
  313. so previous versions probably work, though they weren't properly tested on
  314. 1.11.
  315. 2.0.2 (2017-02-06)
  316. ------------------
  317. * Fix when the check for ``CORS_MODEL`` is done to allow it to properly add
  318. the headers and respond to ``OPTIONS`` requests.
  319. 2.0.1 (2017-01-29)
  320. ------------------
  321. * Add support for specifying 'null' in ``CORS_ORIGIN_WHITELIST``.
  322. 2.0.0 (2017-01-07)
  323. ------------------
  324. * Remove previously undocumented ``CorsModel`` as it was causing migration
  325. issues. For backwards compatibility, any users previously using ``CorsModel``
  326. should create a model in their own app that inherits from the new
  327. ``AbstractCorsModel``, and to keep using the same data, set the model's
  328. ``db_table`` to 'corsheaders_corsmodel'. Users not using ``CorsModel``
  329. will find they have an unused table that they can drop.
  330. * Make sure that ``Access-Control-Allow-Credentials`` is in the response if the
  331. client asks for it.
  332. 1.3.1 (2016-11-09)
  333. ------------------
  334. * Fix a bug with the single check if CORS enabled added in 1.3.0: on Django
  335. < 1.10 shortcut responses could be generated by middleware above
  336. ``CorsMiddleware``, before it processed the request, failing with an
  337. ``AttributeError`` for ``request._cors_enabled``. Also clarified the docs
  338. that ``CorsMiddleware`` should be kept as high as possible in your middleware
  339. stack, above any middleware that can generate such responses.
  340. 1.3.0 (2016-11-06)
  341. ------------------
  342. * Add checks to validate the types of the settings.
  343. * Add the 'Do Not Track' header ``'DNT'`` to the default for
  344. ``CORS_ALLOW_HEADERS``.
  345. * Add 'Origin' to the 'Vary' header of outgoing requests when not allowing all
  346. origins, as per the CORS spec. Note this changes the way HTTP caching works
  347. with your CORS-enabled responses.
  348. * Check whether CORS should be enabled on a request only once. This has had a
  349. minor change on the conditions where any custom signals will be called -
  350. signals will now always be called *before* ``HTTP_REFERER`` gets replaced,
  351. whereas before they could be called before and after. Also this attaches the
  352. attribute ``_cors_enabled`` to ``request`` - please take care that other
  353. code you're running does not remove it.
  354. 1.2.2 (2016-10-05)
  355. ------------------
  356. * Add ``CorsModel.__str__`` for human-readable text
  357. * Add a signal that allows you to add code for more intricate control over when
  358. CORS headers are added.
  359. 1.2.1 (2016-09-30)
  360. ------------------
  361. * Made settings dynamically respond to changes, and which allows you to import
  362. the defaults for headers and methods in order to extend them.
  363. 1.2.0 (2016-09-28)
  364. ------------------
  365. * Drop Python 2.6 support.
  366. * Drop Django 1.3-1.7 support, as they are no longer supported.
  367. * Confirmed Django 1.9 support (no changes outside of tests were necessary).
  368. * Added Django 1.10 support.
  369. * Package as a universal wheel.
  370. 1.1.0 (2014-12-15)
  371. ------------------
  372. * django-cors-header now supports Django 1.8 with its new application loading
  373. system! Thanks @jpadilla for making this possible and sorry for the delay in
  374. making a release.
  375. 1.0.0 (2014-12-13)
  376. ------------------
  377. django-cors-headers is all grown-up :) Since it's been used in production for
  378. many many deployments, I think it's time we mark this as a stable release.
  379. * Switching this middleware versioning over to semantic versioning
  380. * #46 add user-agent and accept-encoding default headers
  381. * #45 pep-8 this big boy up
  382. 0.13 (2014-08-14)
  383. -----------------
  384. * Add support for Python 3
  385. * Updated tests
  386. * Improved docuemntation
  387. * Small bugfixes
  388. 0.12 (2013-09-24)
  389. -----------------
  390. * Added an option to selectively enable CORS only for specific URLs
  391. 0.11 (2013-09-24)
  392. * Added the ability to specify a regex for whitelisting many origin hostnames
  393. at once
  394. 0.10 (2013-09-05)
  395. -----------------
  396. * Introduced port distinction for origin checking
  397. * Use ``urlparse`` for Python 3 support
  398. * Added testcases to project
  399. 0.06 (2013-02-18)
  400. -----------------
  401. * Add support for exposed response headers
  402. 0.05 (2013-01-26)
  403. -----------------
  404. * Fixed middleware to ensure correct response for CORS preflight requests
  405. 0.04 (2013-01-25)
  406. -----------------
  407. * Add ``Access-Control-Allow-Credentials`` control to simple requests
  408. 0.03 (2013-01-22)
  409. -----------------
  410. * Bugfix to repair mismatched default variable names
  411. 0.02 (2013-01-19)
  412. -----------------
  413. * Refactor/pull defaults into separate file
  414. 0.01 (2013-01-19)
  415. -----------------
  416. * Initial release
  417. Keywords: django,cors,middleware,rest,api
  418. Platform: UNKNOWN
  419. Classifier: Development Status :: 5 - Production/Stable
  420. Classifier: Environment :: Web Environment
  421. Classifier: Framework :: Django
  422. Classifier: Framework :: Django :: 1.11
  423. Classifier: Framework :: Django :: 2.0
  424. Classifier: Framework :: Django :: 2.1
  425. Classifier: Framework :: Django :: 2.2
  426. Classifier: Intended Audience :: Developers
  427. Classifier: License :: OSI Approved :: MIT License
  428. Classifier: Operating System :: OS Independent
  429. Classifier: Programming Language :: Python
  430. Classifier: Programming Language :: Python :: 2
  431. Classifier: Programming Language :: Python :: 2.7
  432. Classifier: Programming Language :: Python :: 3
  433. Classifier: Programming Language :: Python :: 3.5
  434. Classifier: Programming Language :: Python :: 3.6
  435. Classifier: Programming Language :: Python :: 3.7
  436. Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
  437. Classifier: Topic :: Software Development :: Libraries :: Python Modules
  438. Requires-Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*