django-markdownx/docs/_modules/markdownx/forms.html
Pouria Hadjibagheri a9f010dc45 documentations.
2017-04-23 13:52:52 +01:00

418 lines
No EOL
24 KiB
HTML

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>markdownx.forms &mdash; Django Markdownx 2.0.0 documentation</title>
<link rel="stylesheet" href="../../_static/css/theme.css" type="text/css" />
<link rel="index" title="Index"
href="../../genindex.html"/>
<link rel="search" title="Search" href="../../search.html"/>
<link rel="top" title="Django Markdownx 2.0.0 documentation" href="../../index.html"/>
<link rel="up" title="Module code" href="../index.html"/>
<script src="../../_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
<a href="../../index.html" class="icon icon-home"> Django Markdownx
</a>
<div class="version">
2.0
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../installation.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../getting_started.html">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../example.html">Example</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../customization.html">Customization</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../translation.html">Translation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../js/js.html">JavaScript</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../markdownx/markdownx.html">MarkdownX Modules</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../license.html">License</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../../index.html">Django Markdownx</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../../index.html">Docs</a> &raquo;</li>
<li><a href="../index.html">Module code</a> &raquo;</li>
<li>markdownx.forms</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<h1>Source code for markdownx.forms</h1><div class="highlight"><pre>
<span></span><span class="c1"># Python internal library.</span>
<span class="kn">from</span> <span class="nn">os</span> <span class="k">import</span> <span class="n">path</span><span class="p">,</span> <span class="n">SEEK_END</span>
<span class="kn">from</span> <span class="nn">uuid</span> <span class="k">import</span> <span class="n">uuid4</span>
<span class="kn">from</span> <span class="nn">collections</span> <span class="k">import</span> <span class="n">namedtuple</span>
<span class="c1"># Django library.</span>
<span class="kn">from</span> <span class="nn">django</span> <span class="k">import</span> <span class="n">forms</span>
<span class="kn">from</span> <span class="nn">django.utils.six</span> <span class="k">import</span> <span class="n">BytesIO</span>
<span class="kn">from</span> <span class="nn">django.core.files.storage</span> <span class="k">import</span> <span class="n">default_storage</span>
<span class="kn">from</span> <span class="nn">django.core.files.uploadedfile</span> <span class="k">import</span> <span class="n">InMemoryUploadedFile</span>
<span class="c1"># Internal.</span>
<span class="kn">from</span> <span class="nn">.utils</span> <span class="k">import</span> <span class="n">scale_and_crop</span><span class="p">,</span> <span class="n">has_javascript</span>
<span class="kn">from</span> <span class="nn">.exceptions</span> <span class="k">import</span> <span class="n">MarkdownxImageUploadError</span>
<span class="kn">from</span> <span class="nn">.settings</span> <span class="k">import</span> <span class="p">(</span>
<span class="n">MARKDOWNX_IMAGE_MAX_SIZE</span><span class="p">,</span>
<span class="n">MARKDOWNX_MEDIA_PATH</span><span class="p">,</span>
<span class="n">MARKDOWNX_UPLOAD_CONTENT_TYPES</span><span class="p">,</span>
<span class="n">MARKDOWNX_UPLOAD_MAX_SIZE</span><span class="p">,</span>
<span class="n">MARKDOWNX_SVG_JAVASCRIPT_PROTECTION</span>
<span class="p">)</span>
<div class="viewcode-block" id="ImageForm"><a class="viewcode-back" href="../../markdownx/docs/forms.html#markdownx.forms.ImageForm">[docs]</a><span class="k">class</span> <span class="nc">ImageForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Used for the handling of images uploaded using the editor through :guilabel:`AJAX`.</span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="n">image</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">FileField</span><span class="p">()</span>
<span class="c1"># Separately defined as it needs to be</span>
<span class="c1"># processed a text file rather than image.</span>
<span class="n">_SVG_TYPE</span> <span class="o">=</span> <span class="s1">&#39;image/svg+xml&#39;</span>
<div class="viewcode-block" id="ImageForm.save"><a class="viewcode-back" href="../../markdownx/docs/forms.html#markdownx.forms.ImageForm.save">[docs]</a> <span class="k">def</span> <span class="nf">save</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">commit</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Saves the uploaded image in the designated location.</span>
<span class="sd"> If image type is not SVG, a byteIO of image content_type is created and</span>
<span class="sd"> subsequently save; otherwise, the SVG is saved in its existing ``charset``</span>
<span class="sd"> as an ``image/svg+xml``.</span>
<span class="sd"> *Note*: The dimension of image files (excluding SVG) are set using ``PIL``.</span>
<span class="sd"> :param commit: If ``True``, the file is saved to the disk;</span>
<span class="sd"> otherwise, it is held in the memory.</span>
<span class="sd"> :type commit: bool</span>
<span class="sd"> :return: An instance of saved image if ``commit is True``,</span>
<span class="sd"> else ``namedtuple(path, image)``.</span>
<span class="sd"> :rtype: bool, namedtuple</span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="n">image</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">files</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;image&#39;</span><span class="p">)</span>
<span class="n">content_type</span> <span class="o">=</span> <span class="n">image</span><span class="o">.</span><span class="n">content_type</span>
<span class="n">file_name</span> <span class="o">=</span> <span class="n">image</span><span class="o">.</span><span class="n">name</span>
<span class="n">image_extension</span> <span class="o">=</span> <span class="n">content_type</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s1">&#39;/&#39;</span><span class="p">)[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">upper</span><span class="p">()</span>
<span class="n">image_size</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">image</span><span class="p">,</span> <span class="s1">&#39;_size&#39;</span><span class="p">)</span>
<span class="k">if</span> <span class="n">content_type</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span> <span class="o">!=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_SVG_TYPE</span><span class="p">:</span>
<span class="c1"># Processing the raster graphic image.</span>
<span class="c1"># Note that vector graphics in SVG format</span>
<span class="c1"># do not require additional processing and</span>
<span class="c1"># may be stored as uploaded.</span>
<span class="n">image</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_process_raster</span><span class="p">(</span><span class="n">image</span><span class="p">,</span> <span class="n">image_extension</span><span class="p">)</span>
<span class="n">image_size</span> <span class="o">=</span> <span class="n">image</span><span class="o">.</span><span class="n">tell</span><span class="p">()</span>
<span class="c1"># Processed file (or the actual file in the case of SVG) is now</span>
<span class="c1"># saved in the memory as a Django object.</span>
<span class="n">uploaded_image</span> <span class="o">=</span> <span class="n">InMemoryUploadedFile</span><span class="p">(</span>
<span class="n">file</span><span class="o">=</span><span class="n">image</span><span class="p">,</span>
<span class="n">field_name</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
<span class="n">name</span><span class="o">=</span><span class="n">file_name</span><span class="p">,</span>
<span class="n">content_type</span><span class="o">=</span><span class="n">content_type</span><span class="p">,</span>
<span class="n">size</span><span class="o">=</span><span class="n">image_size</span><span class="p">,</span>
<span class="n">charset</span><span class="o">=</span><span class="kc">None</span>
<span class="p">)</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_save</span><span class="p">(</span><span class="n">uploaded_image</span><span class="p">,</span> <span class="n">file_name</span><span class="p">,</span> <span class="n">commit</span><span class="p">)</span></div>
<span class="k">def</span> <span class="nf">_save</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">image</span><span class="p">,</span> <span class="n">file_name</span><span class="p">,</span> <span class="n">commit</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Final saving process, called internally after processing tasks are complete.</span>
<span class="sd"> :param image: Prepared image</span>
<span class="sd"> :type image: django.core.files.uploadedfile.InMemoryUploadedFile</span>
<span class="sd"> :param file_name: Name of the file using which the image is to be saved.</span>
<span class="sd"> :type file_name: str</span>
<span class="sd"> :param commit: If ``True``, the image is saved onto the disk.</span>
<span class="sd"> :type commit: bool</span>
<span class="sd"> :return: URL of the uploaded image ``commit=True``, otherwise a namedtuple of ``(path, image)`` where</span>
<span class="sd"> ``path`` is the absolute path generated for saving the file, and ``image`` is the prepared</span>
<span class="sd"> image.</span>
<span class="sd"> :rtype: str, namedtuple</span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="c1"># Defining a universally unique name for the file</span>
<span class="c1"># to be saved on the disk.</span>
<span class="n">unique_file_name</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_unique_file_name</span><span class="p">(</span><span class="n">file_name</span><span class="p">)</span>
<span class="n">full_path</span> <span class="o">=</span> <span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">MARKDOWNX_MEDIA_PATH</span><span class="p">,</span> <span class="n">unique_file_name</span><span class="p">)</span>
<span class="k">if</span> <span class="n">commit</span><span class="p">:</span>
<span class="n">default_storage</span><span class="o">.</span><span class="n">save</span><span class="p">(</span><span class="n">full_path</span><span class="p">,</span> <span class="n">image</span><span class="p">)</span>
<span class="k">return</span> <span class="n">default_storage</span><span class="o">.</span><span class="n">url</span><span class="p">(</span><span class="n">full_path</span><span class="p">)</span>
<span class="c1"># If `commit is False`, return the path and in-memory image.</span>
<span class="n">image_data</span> <span class="o">=</span> <span class="n">namedtuple</span><span class="p">(</span><span class="s1">&#39;image_data&#39;</span><span class="p">,</span> <span class="p">[</span><span class="s1">&#39;path&#39;</span><span class="p">,</span> <span class="s1">&#39;image&#39;</span><span class="p">])</span>
<span class="k">return</span> <span class="n">image_data</span><span class="p">(</span><span class="n">path</span><span class="o">=</span><span class="n">full_path</span><span class="p">,</span> <span class="n">image</span><span class="o">=</span><span class="n">image</span><span class="p">)</span>
<span class="nd">@staticmethod</span>
<span class="k">def</span> <span class="nf">_process_raster</span><span class="p">(</span><span class="n">image</span><span class="p">,</span> <span class="n">extension</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Processing of raster graphic image using Python Imaging Library (PIL).</span>
<span class="sd"> This is where raster graphics are processed to the specifications</span>
<span class="sd"> as defined in ``settings.py``.</span>
<span class="sd"> *Note*: The file needs to be uploaded and saved temporarily in the</span>
<span class="sd"> memory to enable processing tasks using Python Imaging Library (PIL)</span>
<span class="sd"> to take place and subsequently retained until written onto the disk.</span>
<span class="sd"> :param image: Non-SVG image as processed by Django.</span>
<span class="sd"> :type image: django.forms.BaseForm.file</span>
<span class="sd"> :param extension: Image extension (e.g.: png, jpg, gif)</span>
<span class="sd"> :type extension: str</span>
<span class="sd"> :return: The image object ready to be written into a file.</span>
<span class="sd"> :rtype: BytesIO</span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="n">thumb_io</span> <span class="o">=</span> <span class="n">BytesIO</span><span class="p">()</span>
<span class="n">preped_image</span> <span class="o">=</span> <span class="n">scale_and_crop</span><span class="p">(</span><span class="n">image</span><span class="p">,</span> <span class="o">**</span><span class="n">MARKDOWNX_IMAGE_MAX_SIZE</span><span class="p">)</span>
<span class="n">preped_image</span><span class="o">.</span><span class="n">save</span><span class="p">(</span><span class="n">thumb_io</span><span class="p">,</span> <span class="n">extension</span><span class="p">)</span>
<span class="n">thumb_io</span><span class="o">.</span><span class="n">seek</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="n">SEEK_END</span><span class="p">)</span>
<span class="k">return</span> <span class="n">thumb_io</span>
<span class="nd">@staticmethod</span>
<div class="viewcode-block" id="ImageForm.get_unique_file_name"><a class="viewcode-back" href="../../markdownx/docs/forms.html#markdownx.forms.ImageForm.get_unique_file_name">[docs]</a> <span class="k">def</span> <span class="nf">get_unique_file_name</span><span class="p">(</span><span class="n">file_name</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Generates a universally unique ID using Python ``UUID`` and attaches the extension of file name to it.</span>
<span class="sd"> :param file_name: Name of the uploaded file, including the extension.</span>
<span class="sd"> :type file_name: str</span>
<span class="sd"> :return: Universally unique ID, ending with the extension extracted from ``file_name``.</span>
<span class="sd"> :rtype: str</span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="n">extension</span> <span class="o">=</span> <span class="mi">1</span>
<span class="n">extension_dot_index</span> <span class="o">=</span> <span class="mi">1</span>
<span class="n">file_name</span> <span class="o">=</span> <span class="s2">&quot;</span><span class="si">{unique_name}</span><span class="s2">.</span><span class="si">{extension}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span>
<span class="n">unique_name</span><span class="o">=</span><span class="n">uuid4</span><span class="p">(),</span>
<span class="n">extension</span><span class="o">=</span><span class="n">path</span><span class="o">.</span><span class="n">splitext</span><span class="p">(</span><span class="n">file_name</span><span class="p">)[</span><span class="n">extension</span><span class="p">][</span><span class="n">extension_dot_index</span><span class="p">:]</span>
<span class="p">)</span>
<span class="k">return</span> <span class="n">file_name</span></div>
<div class="viewcode-block" id="ImageForm.clean"><a class="viewcode-back" href="../../markdownx/docs/forms.html#markdownx.forms.ImageForm.clean">[docs]</a> <span class="k">def</span> <span class="nf">clean</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Checks the upload against allowed extensions and maximum size.</span>
<span class="sd"> :return: Upload</span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="n">upload</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">cleaned_data</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;image&#39;</span><span class="p">)</span>
<span class="c1"># -----------------------------------------------</span>
<span class="c1"># See comments in `self._error_templates` for</span>
<span class="c1"># additional information on each error.</span>
<span class="c1"># -----------------------------------------------</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">upload</span><span class="p">:</span>
<span class="k">raise</span> <span class="n">MarkdownxImageUploadError</span><span class="o">.</span><span class="n">not_uploaded</span><span class="p">()</span>
<span class="n">content_type</span> <span class="o">=</span> <span class="n">upload</span><span class="o">.</span><span class="n">content_type</span>
<span class="n">file_size</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">upload</span><span class="p">,</span> <span class="s1">&#39;_size&#39;</span><span class="p">)</span>
<span class="k">if</span> <span class="n">content_type</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">MARKDOWNX_UPLOAD_CONTENT_TYPES</span><span class="p">:</span>
<span class="k">raise</span> <span class="n">MarkdownxImageUploadError</span><span class="o">.</span><span class="n">unsupported_format</span><span class="p">()</span>
<span class="k">elif</span> <span class="n">file_size</span> <span class="o">&gt;</span> <span class="n">MARKDOWNX_UPLOAD_MAX_SIZE</span><span class="p">:</span>
<span class="k">raise</span> <span class="n">MarkdownxImageUploadError</span><span class="o">.</span><span class="n">invalid_size</span><span class="p">(</span>
<span class="n">current</span><span class="o">=</span><span class="n">file_size</span><span class="p">,</span>
<span class="n">expected</span><span class="o">=</span><span class="n">MARKDOWNX_UPLOAD_MAX_SIZE</span>
<span class="p">)</span>
<span class="k">elif</span> <span class="p">(</span><span class="n">content_type</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span> <span class="o">!=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_SVG_TYPE</span>
<span class="ow">and</span> <span class="n">MARKDOWNX_SVG_JAVASCRIPT_PROTECTION</span>
<span class="ow">and</span> <span class="n">has_javascript</span><span class="p">(</span><span class="n">upload</span><span class="o">.</span><span class="n">read</span><span class="p">())):</span>
<span class="k">raise</span> <span class="n">MarkdownxImageUploadError</span><span class="p">(</span>
<span class="s1">&#39;Failed security monitoring: SVG file contains JavaScript.&#39;</span>
<span class="p">)</span>
<span class="k">return</span> <span class="n">upload</span></div></div>
</pre></div>
</div>
<div class="articleComments">
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2017 - Adi, Pouria Hadjibagheri.
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'../../',
VERSION:'2.0.0',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="../../_static/jquery.js"></script>
<script type="text/javascript" src="../../_static/underscore.js"></script>
<script type="text/javascript" src="../../_static/doctools.js"></script>
<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/javascript" src="../../_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>