Metadata-Version: 1.0
Name: gocept.collmex
Version: 0.4
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]_
        
        >>> import transaction
        
        
        Customers: ``create_customer`` and ``get_customers``
        ----------------------------------------------------
        
        >>> customer = gocept.collmex.model.Customer()
        >>> customer['Kundennummer'] = 10000
        >>> customer['Firma'] = 'Testkunden'
        >>> collmex.create_customer(customer)
        >>> transaction.commit()
        
        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'
        
        Products: ``create_product`` and ``get_products``
        -------------------------------------------------
        
        Products are created using the ``create_product`` method:
        
        >>> product = gocept.collmex.model.Product()
        >>> product['Produktnummer'] = 'TEST'
        >>> product['Bezeichnung'] = 'Testprodukt'
        >>> product['Produktart'] = 0 # Ware
        >>> product['Verkaufs-Preis'] = 5
        >>> collmex.create_product(product)
        >>> transaction.commit()
        >>> collmex.get_products()[0]['Bezeichnung']
        'Testprodukt'
        
        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'] = 'TEST'
        >>> 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:
        
        >>> 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.4 (2008-12-11)
        ----------------
        
        - Added `get_products` and `create_product`.
        - Added `create_customer`.
        - gocept.collmex.testing.cleanup_collmex() now only deletes any existing data,
        it does not add any sample customers or products, use the API for that.
        
        0.3.1 (2008-12-02)
        ------------------
        
        - Python 2.5 compatibility.
        
        0.3 (2008-12-01)
        ----------------
        
        - Using Windows-1252 as encoding when uploading data (used to be ISO-8859-1).
        - Fixed transaction integration when upload fails.
        
        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
