doc/source/vmm.rst
changeset 578 20141b967c0b
parent 577 4f9079dd4b65
child 579 be0906181a10
equal deleted inserted replaced
577:4f9079dd4b65 578:20141b967c0b
     1 :mod:`VirtualMailManager` ---  Initialization code and some functions
       
     2 =====================================================================
       
     3 
       
     4 .. module:: VirtualMailManager
       
     5   :synopsis: Initialization code and some functions
       
     6 
       
     7 .. moduleauthor:: Pascal Volk <neverseen@users.sourceforge.net>
       
     8 
       
     9 .. toctree::
       
    10    :maxdepth: 2
       
    11 
       
    12 When the VirtualMailManager module, or one of its sub modules, is imported,
       
    13 the following actions will be performed:
       
    14 
       
    15   - :func:`locale.setlocale` (with :const:`locale.LC_ALL`) is called, to set
       
    16     :const:`ENCODING`
       
    17   - :func:`gettext.install` is called, to have 18N support.
       
    18 
       
    19 Constants and data
       
    20 ------------------
       
    21 
       
    22 .. data:: ENCODING
       
    23 
       
    24   The systems current character encoding, e.g. ``'UTF-8'`` or
       
    25   ``'ANSI_X3.4-1968'`` (aka ASCII).
       
    26 
       
    27 
       
    28 Functions
       
    29 ---------
       
    30 
       
    31 .. function:: ace2idna(domainname)
       
    32 
       
    33   Converts the idn domain name *domainname* into punycode.
       
    34 
       
    35   :param domainname: the domain-ace representation (``xn--…``)
       
    36   :type domainname: str
       
    37   :rtype: unicode
       
    38 
       
    39 .. function:: check_domainname(domainname)
       
    40 
       
    41   Returns the validated domain name *domainname*.
       
    42 
       
    43   It also converts the name of the domain from IDN to ASCII, if necessary.
       
    44 
       
    45   :param domainname: the name of the domain
       
    46   :type domainname: :obj:`basestring`
       
    47   :rtype: str
       
    48   :raise VirtualMailManager.errors.VMMError: if the domain name is
       
    49     too long or doesn't look like a valid domain name (label.label.label).
       
    50 
       
    51 .. function:: check_localpart(localpart)
       
    52 
       
    53   Returns the validated local-part *localpart* of an e-mail address.
       
    54 
       
    55   :param localpart: The local-part of an e-mail address.
       
    56   :type localpart: str
       
    57   :rtype: str
       
    58   :raise VirtualMailManager.errors.VMMError: if the local-part is too
       
    59     long or contains invalid characters.
       
    60 
       
    61 .. function:: exec_ok(binary)
       
    62 
       
    63   Checks if the *binary* exists and if it is executable.
       
    64 
       
    65   :param binary: path to the binary
       
    66   :type binary: str
       
    67   :rtype: str
       
    68   :raise VirtualMailManager.errors.VMMError: if *binary* isn't a file
       
    69     or is not executable.
       
    70 
       
    71 .. function:: expand_path(path)
       
    72 
       
    73   Expands paths, starting with ``.`` or ``~``, to an absolute path.
       
    74 
       
    75   :param path: Path to a file or directory
       
    76   :type path: str
       
    77   :rtype: str
       
    78 
       
    79 .. function:: get_unicode(string)
       
    80 
       
    81   Converts `string` to `unicode`, if necessary.
       
    82 
       
    83   :param string: The string taht should be converted
       
    84   :type string: str
       
    85   :rtype: unicode
       
    86 
       
    87 .. function:: idn2ascii(domainname)
       
    88 
       
    89   Converts the idn domain name *domainname* into punycode.
       
    90 
       
    91   :param domainname: the unicode representation of the domain name
       
    92   :type domainname: unicode
       
    93   :rtype: str
       
    94 
       
    95 .. function:: is_dir(path)
       
    96 
       
    97   Checks if *path* is a directory.
       
    98 
       
    99   :param path: Path to a directory
       
   100   :type path: str
       
   101   :rtype: str
       
   102   :raise VirtualMailManager.errors.VMMError: if *path* is not a directory.
       
   103 
       
   104 
       
   105 Examples
       
   106 --------
       
   107 
       
   108   >>> from VirtualMailManager import *
       
   109   >>> ace2idna('xn--pypal-4ve.tld')
       
   110   u'p\u0430ypal.tld'
       
   111   >>> idn2ascii(u'öko.de')
       
   112   'xn--ko-eka.de'
       
   113   >>> check_domainname(u'pаypal.tld')
       
   114   'xn--pypal-4ve.tld'
       
   115   >>> check_localpart('john.doe')
       
   116   'john.doe'
       
   117   >>> exec_ok('usr/bin/vim')
       
   118   Traceback (most recent call last):
       
   119     File "<stdin>", line 1, in <module>
       
   120     File "./VirtualMailManager/__init__.py", line 93, in exec_ok
       
   121       NO_SUCH_BINARY)
       
   122   VirtualMailManager.errors.VMMError: 'usr/bin/vim' is not a file
       
   123   >>> exec_ok('/usr/bin/vim')
       
   124   '/usr/bin/vim'
       
   125   >>> expand_path('.')
       
   126   '/home/user/hg/vmm'
       
   127   >>> get_unicode('hello world')
       
   128   u'hello world'
       
   129   >>> is_dir('~/hg')
       
   130   '/home/user/hg'
       
   131   >>> 
       
   132