Grigoriy Petukhov avatar Grigoriy Petukhov committed 48b55c1

Update docs: enum documentation

Comments (0)

Files changed (12)

 """
 This module provides ``Enum`` class which simplifies work with enumerated list of choices.
 This implementation is specially developed for use in django models.
+
+Example of usage::
+
+    from common import enum
+
+    class Color(enum.Enum):
+        red = enum.Item(1)
+        green = enum.Item(2, 'So greeeen')
+
+
+We defined here two items. They are accessable as ``Color.red`` and ``Color.green``.
+``Color.red`` will give you ``1``. So ``Color.red == 1`` is ``True``.
+
+First item (``Color.red``) has the label same to its key i.e., "red". Second item (``Color.green``) has the custom label.  Labels are used when Color object are queried for the (key, label) pairs. This happens, for example, when we use Color object as the value for the ``choices`` argument of django field::
+
+    class Fruit(models.Model):
+        color = models.IntegerField(choices=Color, default=Color.red)
+
+We can use Color object as ``choices`` argument because ``enum.Enum`` class provides custom __iter__
+method which returs (key, label) pairs.
+
+Also keep in mind that ``Color.red`` is not simple integer. It is like integer but has
+some extra methods. Look example:
+
+    Color.green == 2
+    Color.green.label == "So greeeen"
+    Color.green.key == "green"
+
+Other useful methods of enum.Enum class::
+
+   Color.by_value(1) == Color.red
+   Color.by_key("red") == Color.red
+   Color.values == [Color.red, Color.green]
+   Color.random_value() == "Random value choosed from Color items"
 """
 
 import re
Add a comment to this file

docs/_build/doctrees/environment.pickle

Binary file modified.

Add a comment to this file

docs/_build/doctrees/index.doctree

Binary file modified.

docs/_build/html/.buildinfo

 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 
-tags: 
+config: b33adc5b02c57fd95095c0a7ae214204
+tags: fbb0d17656682115ca4d033fb2f83ba1

docs/_build/html/_sources/index.txt

 .. autoclass:: AutoOneToOneField()
 
 .. autoclass:: JSONField()
+
+Enum
+====
+
+.. automodule:: common.enum
+
+.. autoclass:: AutoOneToOneField()
+
+.. autoclass:: JSONField()

docs/_build/html/genindex.html

   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
     
-    <title>Index &mdash; django-common v0.1.23 documentation</title>
+    <title>Index &mdash; django-common v0.1.31 documentation</title>
     <link rel="stylesheet" href="_static/default.css" type="text/css" />
     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
     <script type="text/javascript">
       var DOCUMENTATION_OPTIONS = {
         URL_ROOT:    '',
-        VERSION:     '0.1.23',
+        VERSION:     '0.1.31',
         COLLAPSE_INDEX: false,
         FILE_SUFFIX: '.html',
         HAS_SOURCE:  true
     <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>
-    <link rel="top" title="django-common v0.1.23 documentation" href="index.html" /> 
+    <link rel="top" title="django-common v0.1.31 documentation" href="index.html" /> 
   </head>
   <body>
     <div class="related">
         <li class="right" >
           <a href="py-modindex.html" title="Python Module Index"
              >modules</a> |</li>
-        <li><a href="index.html">django-common v0.1.23 documentation</a> &raquo;</li> 
+        <li><a href="index.html">django-common v0.1.31 documentation</a> &raquo;</li> 
       </ul>
     </div>  
 
 <table width="100%" class="indextable genindextable"><tr>
   <td width="33%" valign="top"><dl>
     <dt><a href="index.html#module-common.decorators">common.decorators (module)</a></dt>
+    <dt><a href="index.html#module-common.enum">common.enum (module)</a></dt>
     <dt><a href="index.html#module-common.fields">common.fields (module)</a></dt>
 </dl></td>
   <td width="33%" valign="top"><dl>
         <li class="right" >
           <a href="py-modindex.html" title="Python Module Index"
              >modules</a> |</li>
-        <li><a href="index.html">django-common v0.1.23 documentation</a> &raquo;</li> 
+        <li><a href="index.html">django-common v0.1.31 documentation</a> &raquo;</li> 
       </ul>
     </div>
     <div class="footer">

docs/_build/html/index.html

   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
     
-    <title>django-common &mdash; django-common v0.1.23 documentation</title>
+    <title>django-common &mdash; django-common v0.1.31 documentation</title>
     <link rel="stylesheet" href="_static/default.css" type="text/css" />
     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
     <script type="text/javascript">
       var DOCUMENTATION_OPTIONS = {
         URL_ROOT:    '',
-        VERSION:     '0.1.23',
+        VERSION:     '0.1.31',
         COLLAPSE_INDEX: false,
         FILE_SUFFIX: '.html',
         HAS_SOURCE:  true
     <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>
-    <link rel="top" title="django-common v0.1.23 documentation" href="#" /> 
+    <link rel="top" title="django-common v0.1.31 documentation" href="#" /> 
   </head>
   <body>
     <div class="related">
         <li class="right" >
           <a href="py-modindex.html" title="Python Module Index"
              >modules</a> |</li>
-        <li><a href="#">django-common v0.1.23 documentation</a> &raquo;</li> 
+        <li><a href="#">django-common v0.1.31 documentation</a> &raquo;</li> 
       </ul>
     </div>  
 
 </dd></dl>
 
 </div>
+<div class="section" id="module-common.enum">
+<span id="enum"></span><h2>Enum<a class="headerlink" href="#module-common.enum" title="Permalink to this headline">¶</a></h2>
+<p>This module provides <tt class="docutils literal"><span class="pre">Enum</span></tt> class which simplifies work with enumerated list of choices.
+This implementation is specially developed for use in django models.</p>
+<p>Example of usage:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">common</span> <span class="kn">import</span> <span class="n">enum</span>
+
+<span class="k">class</span> <span class="nc">Color</span><span class="p">(</span><span class="n">enum</span><span class="o">.</span><span class="n">Enum</span><span class="p">):</span>
+    <span class="n">red</span> <span class="o">=</span> <span class="n">enum</span><span class="o">.</span><span class="n">Item</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
+    <span class="n">green</span> <span class="o">=</span> <span class="n">enum</span><span class="o">.</span><span class="n">Item</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="s">&#39;So greeeen&#39;</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>We defined here two items. They are accessable as <tt class="docutils literal"><span class="pre">Color.red</span></tt> and <tt class="docutils literal"><span class="pre">Color.green</span></tt>.
+<tt class="docutils literal"><span class="pre">Color.red</span></tt> will give you <tt class="docutils literal"><span class="pre">1</span></tt>. So <tt class="docutils literal"><span class="pre">Color.red</span> <span class="pre">==</span> <span class="pre">1</span></tt> is <tt class="xref docutils literal"><span class="pre">True</span></tt>.</p>
+<p>First item (<tt class="docutils literal"><span class="pre">Color.red</span></tt>) has the label same to its key i.e., &#8220;red&#8221;. Second item (<tt class="docutils literal"><span class="pre">Color.green</span></tt>) has the custom label.  Labels are used when Color object are queried for the (key, label) pairs. This happens, for example, when we use Color object as the value for the <tt class="docutils literal"><span class="pre">choices</span></tt> argument of django field:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Fruit</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
+    <span class="n">color</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">IntegerField</span><span class="p">(</span><span class="n">choices</span><span class="o">=</span><span class="n">Color</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="n">Color</span><span class="o">.</span><span class="n">red</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>We can use Color object as <tt class="docutils literal"><span class="pre">choices</span></tt> argument because <tt class="docutils literal"><span class="pre">enum.Enum</span></tt> class provides custom __iter__
+method which returs (key, label) pairs.</p>
+<p>Also keep in mind that <tt class="docutils literal"><span class="pre">Color.red</span></tt> is not simple integer. It is like integer but has
+some extra methods. Look example:</p>
+<blockquote>
+Color.green == 2
+Color.green.label == &#8220;So greeeen&#8221;
+Color.green.key == &#8220;green&#8221;</blockquote>
+<p>Other useful methods of enum.Enum class:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="n">Color</span><span class="o">.</span><span class="n">by_value</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="o">==</span> <span class="n">Color</span><span class="o">.</span><span class="n">red</span>
+<span class="n">Color</span><span class="o">.</span><span class="n">by_key</span><span class="p">(</span><span class="s">&quot;red&quot;</span><span class="p">)</span> <span class="o">==</span> <span class="n">Color</span><span class="o">.</span><span class="n">red</span>
+<span class="n">Color</span><span class="o">.</span><span class="n">values</span> <span class="o">==</span> <span class="p">[</span><span class="n">Color</span><span class="o">.</span><span class="n">red</span><span class="p">,</span> <span class="n">Color</span><span class="o">.</span><span class="n">green</span><span class="p">]</span>
+<span class="n">Color</span><span class="o">.</span><span class="n">random_value</span><span class="p">()</span> <span class="o">==</span> <span class="s">&quot;Random value choosed from Color items&quot;</span>
+</pre></div>
+</div>
+</div>
 </div>
 
 
 <li><a class="reference internal" href="#module-common.pagination">Pagination</a></li>
 <li><a class="reference internal" href="#module-common.forms">Forms</a></li>
 <li><a class="reference internal" href="#module-common.fields">Model Fields</a></li>
+<li><a class="reference internal" href="#module-common.enum">Enum</a></li>
 </ul>
 </li>
 </ul>
         <li class="right" >
           <a href="py-modindex.html" title="Python Module Index"
              >modules</a> |</li>
-        <li><a href="#">django-common v0.1.23 documentation</a> &raquo;</li> 
+        <li><a href="#">django-common v0.1.31 documentation</a> &raquo;</li> 
       </ul>
     </div>
     <div class="footer">

docs/_build/html/objects.inv

 # Sphinx inventory version 2
 # Project: django-common
-# Version: 0.1.23
+# Version: 0.1.31
 # The remainder of this file is compressed using zlib.
-xڕ��j�0��y
-A{�h�������{ki�(H� ��}#�n��)�E,��Vî
-3\�s0��mI��k�V
+xڕ�ˊ1E�~E`�v��f
+

docs/_build/html/py-modindex.html

   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
     
-    <title>Python Module Index &mdash; django-common v0.1.23 documentation</title>
+    <title>Python Module Index &mdash; django-common v0.1.31 documentation</title>
     <link rel="stylesheet" href="_static/default.css" type="text/css" />
     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
     <script type="text/javascript">
       var DOCUMENTATION_OPTIONS = {
         URL_ROOT:    '',
-        VERSION:     '0.1.23',
+        VERSION:     '0.1.31',
         COLLAPSE_INDEX: false,
         FILE_SUFFIX: '.html',
         HAS_SOURCE:  true
     <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>
-    <link rel="top" title="django-common v0.1.23 documentation" href="index.html" />
+    <link rel="top" title="django-common v0.1.31 documentation" href="index.html" />
  
 
 
         <li class="right" >
           <a href="#" title="Python Module Index"
              >modules</a> |</li>
-        <li><a href="index.html">django-common v0.1.23 documentation</a> &raquo;</li> 
+        <li><a href="index.html">django-common v0.1.31 documentation</a> &raquo;</li> 
       </ul>
     </div>  
 
      <tr class="cg-1">
        <td></td>
        <td>&nbsp;&nbsp;&nbsp;
+       <a href="index.html#module-common.enum"><tt class="xref">common.enum</tt></a></td><td>
+       <em></em></td></tr>
+     <tr class="cg-1">
+       <td></td>
+       <td>&nbsp;&nbsp;&nbsp;
        <a href="index.html#module-common.fields"><tt class="xref">common.fields</tt></a></td><td>
        <em></em></td></tr>
      <tr class="cg-1">
         <li class="right" >
           <a href="#" title="Python Module Index"
              >modules</a> |</li>
-        <li><a href="index.html">django-common v0.1.23 documentation</a> &raquo;</li> 
+        <li><a href="index.html">django-common v0.1.31 documentation</a> &raquo;</li> 
       </ul>
     </div>
     <div class="footer">

docs/_build/html/search.html

   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
     
-    <title>Search &mdash; django-common v0.1.23 documentation</title>
+    <title>Search &mdash; django-common v0.1.31 documentation</title>
     <link rel="stylesheet" href="_static/default.css" type="text/css" />
     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
     <script type="text/javascript">
       var DOCUMENTATION_OPTIONS = {
         URL_ROOT:    '',
-        VERSION:     '0.1.23',
+        VERSION:     '0.1.31',
         COLLAPSE_INDEX: false,
         FILE_SUFFIX: '.html',
         HAS_SOURCE:  true
     <script type="text/javascript" src="_static/underscore.js"></script>
     <script type="text/javascript" src="_static/doctools.js"></script>
     <script type="text/javascript" src="_static/searchtools.js"></script>
-    <link rel="top" title="django-common v0.1.23 documentation" href="index.html" />
+    <link rel="top" title="django-common v0.1.31 documentation" href="index.html" />
   <script type="text/javascript">
     jQuery(function() { Search.loadIndex("searchindex.js"); });
   </script>
         <li class="right" >
           <a href="py-modindex.html" title="Python Module Index"
              >modules</a> |</li>
-        <li><a href="index.html">django-common v0.1.23 documentation</a> &raquo;</li> 
+        <li><a href="index.html">django-common v0.1.31 documentation</a> &raquo;</li> 
       </ul>
     </div>  
 
         <li class="right" >
           <a href="py-modindex.html" title="Python Module Index"
              >modules</a> |</li>
-        <li><a href="index.html">django-common v0.1.23 documentation</a> &raquo;</li> 
+        <li><a href="index.html">django-common v0.1.31 documentation</a> &raquo;</li> 
       </ul>
     </div>
     <div class="footer">

docs/_build/html/searchindex.js

-Search.setIndex({objects:{"common.forms":{DeleteForm:[0,1,1],build_form:[0,2,1]},"common.fields":{JSONField:[0,1,1],AutoOneToOneField:[0,1,1]},"common.pagination":{paginate:[0,2,1]},"common.decorators":{ajax:[0,2,1],render_to:[0,2,1]},common:{forms:[0,0,1],fields:[0,0,1],pagination:[0,0,1],decorators:[0,0,1]}},terms:{all:0,code:0,just:0,create_us:0,follow:0,speed:0,yet:0,onetoonefield:0,redirect:0,onli:0,depend:0,requestcontext:0,field:0,except:0,build_form:0,blog:0,is_valid:0,dict:0,under:0,els:0,save:0,non:0,sourc:0,"return":0,get:0,auto:0,auth:0,bound:0,foo_list:0,know:0,frame_s:0,get_object_or_404:0,should:0,dramat:0,thumbnail:0,item:0,common:0,contain:0,output:0,postid:0,where:0,page:0,view:0,pleas:0,set:0,easy_instal:0,postform:0,video:0,arg:0,append:0,gmail:0,index:0,unbound:0,extend:0,confirm:0,per:0,profil:0,delet:0,larg:0,icq:0,foo:0,method:0,core:0,parent:0,usag:0,conjunct:0,ajax:0,path:0,post:0,convert:0,obj:0,could:0,thing:0,instanc:0,pagin:0,action:0,typic:0,com:0,first:0,render:0,modul:0,number:0,visibl:0,wrap:0,instal:0,installed_app:0,autoonetoonefield:0,hood:0,from:0,creat:0,messag:0,next:0,json:0,includ:0,store:0,more:0,cleaned_data:0,option:0,form:0,some:0,post_delet:0,jpg:0,func:0,russian:0,render_to:0,info:0,look:0,work:0,can:0,error:0,jsonfield:0,initi:0,robin:0,def:0,login_requir:0,"_request":0,request:0,queryset:0,ani:0,templat:0,packag:0,kwarg:0,softwaremaniac:0,have:0,pip:0,deleteform:0,serial:0,doe:0,decor:0,develop:0,want:0,allow:0,object_list:0,how:0,html:0,build:0,which:0,batman:0,you:0,simplifi:0,http:0,thi:0,integerfield:0,oject:0,org:0,object:0,post_creat:0,rais:0,user:0,autom:0,data:0,"class":0,task:0,post_list:0,url:0,descript:0,django:0,deni:0,exampl:0,endfor:0,model:0,per_pag:0},objtypes:{"0":"py:module","1":"py:class","2":"py:function"},titles:["django-common"],objnames:{"0":"Python module","1":"Python class","2":"Python function"},filenames:["index"]})
+Search.setIndex({objects:{"common.forms":{DeleteForm:[0,1,1],build_form:[0,2,1]},"common.fields":{JSONField:[0,1,1],AutoOneToOneField:[0,1,1]},"common.pagination":{paginate:[0,2,1]},"common.decorators":{ajax:[0,2,1],render_to:[0,2,1]},common:{forms:[0,0,1],fields:[0,0,1],pagination:[0,0,1],"enum":[0,0,1],decorators:[0,0,1]}},terms:{all:0,code:0,just:0,queri:0,random:0,becaus:0,by_valu:0,create_us:0,follow:0,speed:0,yet:0,onetoonefield:0,redirect:0,access:0,onli:0,depend:0,requestcontext:0,also:0,except:0,build_form:0,blog:0,is_valid:0,dict:0,under:0,els:0,save:0,custom:0,non:0,sourc:0,"return":0,quiri:[],thei:0,get:0,auto:0,auth:0,easy_instal:0,foo_list:0,know:0,special:0,choic:0,frame_s:0,like:0,get_object_or_404:0,should:0,list:0,dramat:0,integ:0,thumbnail:0,item:0,common:0,contain:0,output:0,postid:0,where:0,page:0,view:0,pleas:0,set:0,greeeen:0,mind:0,postform:0,second:0,video:0,arg:0,happen:0,append:0,gmail:0,index:0,unbound:0,extend:0,confirm:0,enumer:0,per:0,label:0,profil:0,delet:0,larg:0,"import":0,icq:0,foo:0,method:0,red:0,core:0,parent:0,"enum":0,usag:0,conjunct:0,here:0,how:0,ajax:0,path:0,post:0,valu:0,convert:0,obj:0,retur:0,could:0,keep:0,thing:0,instanc:0,pagin:0,action:0,implement:0,com:0,other:0,first:0,render:0,extra:0,color:0,modul:0,bound:0,visibl:0,wrap:0,instal:0,installed_app:0,autoonetoonefield:0,hood:0,kei:0,from:0,creat:0,random_valu:0,two:0,messag:0,next:0,json:0,includ:0,typic:0,store:0,more:0,cleaned_data:0,option:0,form:0,some:0,argument:0,post_delet:0,"__iter__":0,jpg:0,func:0,russian:0,number:0,"true":0,render_to:0,info:0,look:0,"default":0,work:0,defin:0,can:0,error:0,jsonfield:0,initi:0,robin:0,def:0,login_requir:0,"_request":0,give:0,request:0,queryset:0,ani:0,templat:0,packag:0,kwarg:0,softwaremaniac:0,have:0,pip:0,deleteform:0,serial:0,doe:0,decor:0,develop:0,want:0,allow:0,object_list:0,when:0,same:0,field:0,html:0,build:0,which:0,batman:0,you:0,simpl:0,simplifi:0,http:0,thi:0,integerfield:0,oject:0,by_kei:0,org:0,object:0,post_creat:0,fruit:0,user:0,pair:0,autom:0,data:0,"class":0,task:0,post_list:0,url:0,descript:0,rais:0,django:0,deni:0,exampl:0,green:0,endfor:0,choos:0,model:0,per_pag:0,provid:0},objtypes:{"0":"py:module","1":"py:class","2":"py:function"},titles:["django-common"],objnames:{"0":"Python module","1":"Python class","2":"Python function"},filenames:["index"]})
 .. autoclass:: AutoOneToOneField()
 
 .. autoclass:: JSONField()
+
+Enum
+====
+
+.. automodule:: common.enum
+
+.. autoclass:: AutoOneToOneField()
+
+.. autoclass:: JSONField()
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.