Metadata-Version: 1.0
Name: gocept.collmex
Version: 0.2
Summary: Python-bindings for the Collmex import/export API
Home-page: UNKNOWN
Author: gocept
Author-email: mail@gocept.com
License: ZPL 2.1
Description: .. contents::
        
        Introduction
        ============
        
        Collmex is an online ERP system for (small) companies with a focus on simple
        accounting. <http://www.collmex.de> (Note: Collmex is Germany-based but seems
        to support English. You're bound to stumble over German strings, though.)
        
        This package aims to provide pythonic bindings to program against Collmex'
        API. It includes transaction management for integration with the ZODB or other
        databases that can integrate with the `transaction` package.
        
        
        Collmex API
        ===========
        
        Collmex provides a POST- and CSV-based API, which is encapsulated into a
        utility that provides methods for the various CSV record types.  API
        documentation is available at
        http://www.collmex.de/cgi-bin/cgi.exe?1005,1,help,api.
        
        
        The collmex object
        ------------------
        
        The collmex object is a central place to access collmex. In the Zope 3 jargon
        it is a global utility:
        
        >>> import os
        >>> import gocept.collmex.collmex
        >>> collmex = gocept.collmex.collmex.Collmex(
        ...     os.environ['collmex_customer'], os.environ['collmex_company'],
        ...     os.environ['collmex_username'], os.environ['collmex_password'])
        
        
        Transaction integration
        -----------------------
        
        gocept.collmex has support for transaction integration. All modifying calls are
        buffered until the transaction is commited. XXX explain more.
        
        [#pre-flight-cleanup]_ [#invalid-login]_
        
        
        
        Customers: ``get_customers``
        ----------------------------
        
        Customers can be listed using the get_customers method:
        
        >>> customers = collmex.get_customers()
        >>> customers
        [<gocept.collmex.model.Customer object at 0x...>,
        <gocept.collmex.model.Customer object at 0x...>]
        >>> len(customers)
        2
        
        The first customer is the generic one:
        
        >>> customer = customers[0]
        >>> customer['Satzart']
        'CMXKND'
        >>> customer['Kundennummer']
        '9999'
        >>> customer['Firma']
        'Allgemeiner Gesch\xe4ftspartner'
        
        
        The second customer is one created during test setup:
        
        >>> customer = customers[1]
        >>> customer['Satzart']
        'CMXKND'
        >>> customer['Kundennummer']
        '10000'
        >>> customer['Firma']
        'Testkunden'
        
        Invoices: ``create_invoice`` and ``get_invoices``
        -------------------------------------------------
        
        Invoices are created using the ``create_invoice`` method:
        
        >>> import datetime
        >>> start_date = datetime.datetime.now()
        >>> item = gocept.collmex.model.InvoiceItem()
        >>> item['Kunden-Nr'] = '10000'
        >>> item['Rechnungsnummer'] = 100000
        >>> item['Menge'] = 3
        >>> item['Produktnummer'] = 'TRAFFIC'
        >>> item['Rechnungstext'] = 'item text'
        >>> item['Positionstyp'] = 0
        >>> collmex.create_invoice([item])
        
        
        
        Invoices can be looked up again, using the ``get_invoices`` method. However, as
        discussed above the invoice was only registered for addition. Querying right
        now does *not* return the invoice:
        
        >>> collmex.get_invoices(customer_id='10000', start_date=start_date)
        []
        
        After committing, the invoice is found:
        
        >>> import transaction
        >>> transaction.commit()
        >>> collmex.get_invoices(customer_id='10000',
        ...                      start_date=start_date)[0]['Rechnungstext']
        'item text'
        
        
        
        .. [#pre-flight-cleanup] First we need to clean up the Collmex environment:
        
        >>> import gocept.collmex.testing
        >>> gocept.collmex.testing.cleanup_collmex()
        
        .. [#invalid-login] Invalid login information raises an exception:
        
        >>> collmex_invalid = gocept.collmex.collmex.Collmex(
        ...     os.environ['collmex_customer'], os.environ['collmex_company'],
        ...     os.environ['collmex_username'], 'invalid')
        >>> collmex_invalid.get_invoices(customer_id='10000')
        Traceback (most recent call last):
        ...
        APIError: ('101004', 'Benutzer oder Kennwort nicht korrekt')
        
        
        Changes
        =======
        
        0.2 (2008-11-28)
        ----------------
        
        - Modifications for changed Collmex API.
        - Added ``get_customers`` to query customers (API ``CUSTOMER_GET``).
        
        0.1 (2008-10-14)
        ----------------
        
        - first release. Supports getting and storing invoices.
        
Platform: UNKNOWN
