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 .. data:: __author__

    28 

    29   The author's name

    30 

    31 .. data:: __date__

    32 

    33   The release date

    34 

    35 .. data:: __version__

    36 

    37   VirtualMailManager's version

    38 

    39 

    40 Functions

    41 ---------

    42 

    43 .. function:: ace2idna(domainname)

    44 

    45   Converts the idn domain name *domainname* into punycode.

    46 

    47   :param domainname: the domain-ace representation (``xn--…``)

    48   :type domainname: str

    49   :rtype: unicode

    50 

    51 .. function:: check_domainname(domainname)

    52 

    53   Returns the validated domain name *domainname*.

    54 

    55   It also converts the name of the domain from IDN to ASCII, if necessary.

    56 

    57   :param domainname: the name of the domain

    58   :type domainname: :obj:`basestring`

    59   :rtype: str

    60   :raise VirtualMailManager.Exceptions.VMMException: if the domain name is

    61     too long or doesn't look like a valid domain name (label.label.label).

    62 

    63 .. function:: check_localpart(localpart)

    64 

    65   Returns the validated local-part *localpart* of an e-mail address.

    66 

    67   :param localpart: The local-part of an e-mail address.

    68   :type localpart: str

    69   :rtype: str

    70   :raise VirtualMailManager.Exceptions.VMMException: if the local-part is too

    71     long or contains invalid characters.

    72 

    73 .. function:: exec_ok(binary)

    74 

    75   Checks if the *binary* exists and if it is executable.

    76 

    77   :param binary: path to the binary

    78   :type binary: str

    79   :rtype: str

    80   :raise VirtualMailManager.Exceptions.VMMException: if *binary* isn't a file

    81     or is not executable.

    82 

    83 .. function:: expand_path(path)

    84 

    85   Expands paths, starting with ``.`` or ``~``, to an absolute path.

    86 

    87   :param path: Path to a file or directory

    88   :type path: str

    89   :rtype: str

    90 

    91 .. function:: get_unicode(string)

    92 

    93   Converts `string` to `unicode`, if necessary.

    94 

    95   :param string: The string taht should be converted

    96   :type string: str

    97   :rtype: unicode

    98 

    99 .. function:: idn2ascii(domainname)

   100 

   101   Converts the idn domain name *domainname* into punycode.

   102 

   103   :param domainname: the unicode representation of the domain name

   104   :type domainname: unicode

   105   :rtype: str

   106 

   107 .. function:: is_dir(path)

   108 

   109   Checks if *path* is a directory.

   110 

   111   :param path: Path to a directory

   112   :type path: str

   113   :rtype: str

   114   :raise VirtualMailManager.Exceptions.VMMException: if *path* is not a

   115     directory.

   116 

   117 

   118 Examples

   119 --------

   120 

   121     >>> from VirtualMailManager import *

   122     >>> ace2idna('xn--pypal-4ve.tld')

   123     u'p\u0430ypal.tld'

   124     >>> idn2ascii(u'öko.de')

   125     'xn--ko-eka.de'

   126     >>> check_domainname(u'pаypal.tld')

   127     'xn--pypal-4ve.tld'

   128     >>> check_localpart('john.doe')

   129     'john.doe'

   130     >>> exec_ok('usr/bin/vim')

   131     Traceback (most recent call last):

   132       File "<stdin>", line 1, in <module>

   133       File "./VirtualMailManager/__init__.py", line 93, in exec_ok

   134         NO_SUCH_BINARY)

   135     VirtualMailManager.Exceptions.VMMException: 'usr/bin/vim' is not a file

   136     >>> exec_ok('/usr/bin/vim')

   137     '/usr/bin/vim'

   138     >>> expand_path('.')

   139     '/home/user/hg/vmm'

   140     >>> get_unicode('hello world')

   141     u'hello world'

   142     >>> is_dir('~/hg')

   143     '/home/user/hg'

   144     >>> 

   145