{
    "info": {
        "author": "Stian Soiland-Reyes",
        "author_email": "stian@soiland-reyes.com",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 7 - Inactive"
        ],
        "description": "================\nforgetSQL readme\n================\n\n:Author: Stian Soiland <stian@soiland.no>\n:WWW: http://forgetsql.sourceforge.net/\n:License: GNU Lesser General Public License (LGPL)\n          See the file COPYING for details.\n:Status: unfinished\n:Abstract:\n    forgetSQL is a Python module for accessing SQL databases by creating\n    classes that maps SQL tables to objects, normally one class pr. SQL\n    table. The idea is to forget everything about SQL and just worrying\n    about normal classes and objects.\n\n.. contents:: Contents\n\n\nInstallation\n============\n\nInstallation of the forgetSQL module is pretty straight\nforward:\n    \n    python setup.py install\n\nThis will install forgetSQL.py into site-packages/ of your \nPython distribution.\n\n\nDependencies\n------------\n\n* Python 2.2.1 (True/False, new style classes, classmethods, iterators)\n* Some database module (tested: MySQLdb, psycopg)\n\nIf using psycopg, mx.DateTime is needed to avoid a psycopg\nbug related to re-inserting dates. psycopg depends on mx.DateTime, so\nthat shouldn't be a problem.\n\n\nWhat is forgetSQL?\n==================\n\nWhy forgetSQL?\n--------------\n\nLet's start by showing an example using an imaginary database\n``mydatabase``:\n\nThis example is based on these SQL tables:\n\naccount\n~~~~~~~\n\n===========  =================  =======\naccountid    fullname           groupid\n===========  =================  =======\nstain        Stian Soiland      15\nmagnun       Magnus Nordseth    15\nstornes      Sverre Stornes     17\nmjaavatt     Erlend Mjaavatten  15\n===========  =================  =======\n\n\ngroup\n~~~~~\n\n=======  ====\ngroupid  name \n=======  ====\n15       unix \n17       tie\n=======  ====\n\nAnd should output something like::\n\n    Account details for Stian S\ufffdiland\n    Group unix (15)\n    Other members:\n    Magnus Nordseth\n    Erlend Mjaavatten\n\n\nIn regular SQL programming, this could be done something like this::\n\n    cursor = dbconn.cursor()\n    cursor.execute(\"SELECT fullname,groupid FROM account WHERE accountid=%s\", \n                   ('stain',))    \n    fullname,groupid = cursor.fetchone()\n    print \"Account details for\", fullname\n\n    cursor.execute(\"SELECT name FROM group WHERE groupid=%s\" % groupid)\n    (groupname,) = cursor.fetchone()\n    print \"Group %s (%s)\" % (groupid, name)\n\n    cursor.execute(\"\"\"SELECT fullname \n                      FROM account JOIN group USING (groupid)\n                      WHERE group.groupid=%s AND\n                            NOT account.accountid=%s\"\"\",\n                   (groupid, accountid))\n    print \"Other members:\"\n    for (membername,) in cursor.fetchall():\n        print membername\n\n\nNow, using forgetSQL::\n\n    from mydatabase import *\n    account = Account(\"stain\") # primary key\n    print \"Account details for\", account.fullname\n    group = account.group\n    print \"Group %s (%s)\" % (group.name, group.groupid)\n    print \"Other members: \"\n    \n    for member in group.getChildren(Account):\n        # find Account with group as foreign key\n        if member <> account:\n            print member.fullname\n\n\nNotice the difference in size and complexity of these two examples.\n\nThe first example is tightly bound against SQL. The programmer is forced\nto think about SQL instead of the real code. This programming style \ntends to move high-level details to SQL, even if it is not neccessary.\nIn this example, when getting \"other members\", the detail of skipping\nthe active user is done in SQL. \n\nThis would hardly save any CPU time on modern computers, but has made\nthe code more complex.  Thinking in SQL makes your program very large,\nas everything can be solved by some specialized SQL. Trying to change \nyour program or database structure at a later time would be a nightmare.\n\nNow, forgetSQL removes all those details for the every-day-SQL tasks. It\nwill not be hyper-effective or give you points in the\nlargest-join-ever-possible-contest, but it will help you focus on what\nyou should be thinking of, making your program work.\n\nIf you at a later point (when everything runs without failures)\ndiscovers that you need to optimize something with a mega-query in SQL,\nyou could just replace that code with regular SQL operations.\nOf course, if you've been using test-driven development (like in \nhttp://c2.com/cgi/wiki?ExtremeProgramming ) your tests will show if\nthe replaced code works.\n\nAnother alternative could be to use views and stored procedure, and\nlayer forgetSQL on top of those views and procedures. This has never\nbeen tested, though. =)\n\nWhat does forgetSQL do?\n-----------------------\n\nFor each table in your database, a class is created. Each instance\ncreated of these classes refer to a row in the given table. Each\ninstance have attributes that refer to the fields in the database. \nNote that the instance is not created until you access that particular\nrow.\n\nSo accessing a column of a row is simply accessing the attribute\n``row.column``.  Now, if this column is a reference to another table, a\nforeign key, instead of an identifier you will in ``row.column`` find an \ninstance from the other table, ie. from the other class.\n\nThis is what happens in the example above, ``group = account.group``\nretrieves this instance. Further attribute access within this instance\nis resolved from the matching row in the group table.\n\nIf you want to change some value, you could just change the attribute\nvalue. In the example, if you want to change my name, simply run\n``account.fullname = \"Knut Carlsen\"`` (my boss). \n\nYou can retrieve every row in some table that refers to the current\nobject. This is what happens in ``group.getChildren(Account)``, which will\nreturn a list of those Accounts that have a foreign key refering to\n``group``. \n\nIf you retrieve the objects several times, the constructor will return\nthe same object the second time (unless some timeout has expired). This\nmeans that changes done to the object is immediately visible to all\ninstances. This is to reflect normal behaviour in object oriented\nprogramming.  \n\n    >>> stain = Account(\"stain\")\n    >>> stain2 = Account(\"stain\")\n    >>> stain.fullname = \"Knut Carlsen\"\n    >>> print stain2.fullname\n    Knut Carlsen\n\n\nWhat does forgetSQL not do?\n---------------------------\n\nforgetSQL is not a way to store objects in a database. It is a way to\nuse databases as objects. You cannot store arbitrary objects in the\ndatabase unless you use pickling.\n\nforgetSQL does not help you with database design, although you might\nchoose a development style that uses regular classes and objects at\nfirst, and then design the database afterwards. You could then change\nyour classes to use forgetSQL for data retrieval and storage, and later\npossibly replace forgetSQL classes with even more advanced objects.\n\nforgetSQL does not remove the need of heavy duty SQL. In some\nsituations, SQL is simply the best solution. forgetSQL might involve\nmany SQL operations for something that could be done in a single\noperations with a large magic query. If something does not scale up\nwith forgetSQL, even if you refactored your code, you might try using\nSQL instead.  This example would use excessive time in a table with a\nmillion rows::\n\n    for row in table.getAll():\n        row.backedUp = True\n        row.save()\n\nThis would involve creating one million object instances (each row), one\nmillion SELECTs (to get the other values that needs to be saved), and\none million UPDATEs.  By using ``getAllIterator`` you could reduce this to\njust one million UPDATEs (one SELECT, reusing the same object), but\nstill it would be far much slower than ``UPDATE table SET\nbackedUp=true``.\n\nforgetSQL does not support commits/rollback. This might be implemented\nlater, but I'm still unsure of how to actually use this in programming.\nAny suggestions are welcome.\n\nKeeping in sync\n~~~~~~~~~~~~~~~\n\nforgetSQL does not ensure that objects in memory are in sync with what\nis stored in the database. The values in the object will be a snapshot\nof how the row were at the time you first tried to retrieve an\nattribute. If you change some value, and then save the object, the row\nis updated to your version, no matter what has happened in the database\nmeanwhile. An object does not timeout while in memory, it does not\nrefresh it's values unless you call ``_loadDB()`` manually, as\nautomatically updating could confuse programmers. However, a timeout\nvalue is set, and if exceeded, *new* objects retrieved from database\n(ie. ``Account(\"stain\")`` will be fresh.\n\nIt is not easy to make a general way to ensure objects are updated. For\ninstance, always checking it could be heavy. It could also confuse some\nprograms if an object suddenly changes some of it's attributes without\ntelling, this could fuck up any updates the program is attempting to do.\nOn the other hand, saving a changed object as forgetSQL is now, will\noverwrite *all* attributes, not just the changed ones.\n\n\nUsage\n=====\n\nforgetsql-generate\n------------------\n\nBefore you can use forgetSQL, you will need to generate a module\ncontaing the classes representing database tables. Luckily, forgetSQL\nships with a program that can do this for you by guessing.\n\nThe program is called ``forgetsql-generate`` and should be installed by\n``setup.py`` or the packaging system. You might need the devel-version\nof the forgetSQL package.\n\nCreate a file ``tables.txt``, with a list of database tables, one per\nline. (This is needed since there is no consistent way to query a\ndatabase about it's tables)\n\nThen generate the module representing your tables::\n\n    forgetsql-generate --dbmodule psycopg --username=johndoe\n                         --password=Jens1PuLe --database=genious\n                         --tables tables.txt --output Genious.py\n\nAlternative, you could pipe the table list to ``forgetsql-generate``\nand avoid ``--tables`` -- and likewise drop ``--output`` and capture stdout \nfrom forgetsql-generate.\n\nThe generated module is ready for use, except that you need should\nset database connecting details. One possible way is included in the\ngenerated code, commented out and without a password. \n\nIt is recommended to set connection details from the outside instead,\nsince the tables might be used by different parts of a system using\ndifferent database passwords, connection details could be in a\nconfiguration file, you need persistent database connections, etc. \n\nThe way to do this is to set Genious._Wrapper.cursor to a cursor\nmethod, and Genious._Wrapper._dbModule to the database module used::\n\n    import Genious\n    import psycopg\n    conn = psycopg.connect(user=\"blal\", pass=\"sdlksdlk\", database=\"blabla\")\n    Genious._Wrapper.cursor = conn.cursor()\n    Genious._Wrapper._dbModule = psycopg\n\nThis should be refactored to a more userfriendly interface. \n\n\nNormal use\n----------\n\nWe'll call a class that is a representation of a database table a\nforgetter, because it inherits forgetSQL.Forgetter.\nThis chapter will present normal usage of such forgetters by examples.\n\nGetting a row by giving primary key\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nExample::\n\n    account = Account(\"stain\")\n    print account.fullname\n\nIf the primary key is wrong (ie. the row does not exist) accessing\n``account.fullname`` will raise ``forgetSQL.NotFound``. The object is\nactually not loaded from the database until a attribute is read.\n(delayed loading) One problem with that is that ``forgetSQL.NotFound``\nwill not be raised until the attribute is read.\n\nTo test if the primary key is valid, force a load::\n\n    account = Account(\"stain\")\n    try:    \n        account.load()\n    except forgetSQL.NotFound():\n        print \"Cannot find stain\"\n        return\n\n\nGetting all rows in a table\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nExample::\n\n    allAccounts = Account.getAll()\n    for account in allAccounts:\n        print account.accountid, account.fullname\n\nNote that ``getAll`` is a class method, so it is available even before\ncreating some ``Account``. The returned list will be empty if nothing is\nfound.\n\nAlso note that if what you want to do is to iterate, using\n``getAllIterator()`` would work well. This avoids creating all objects\nat once.\n\nTo create a new row in a table\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nExample::\n\n    account = Account()\n    account.accountid = \"jennyme\" # primary key\n    account.fullname = \"Jenny Marie Ellingsaeter\"\n    account.save()\n\nIf you have forgotten to set some required fields, save() will fail. If\nyou don't set the primary key, forgetSQL will try to guess the sequence\nname (tablename_primarykey_seq) to retrieve a new one. This might or\nmight not work. For MySQL some other magic is involved, but it should\nwork.\n\n\nChange some attribute\n~~~~~~~~~~~~~~~~~~~~~\n\nExample::\n\n    account = Account(\"stain\")\n    account.fullname = \"Stian Stornes\" # got married to a beautiful man\n\nYou can choose wether you want to call ``save()`` or not. If you don't call\n``save()``, the object will be saved when the object reference disappaers\n(ie. del account, end of function, etc.) and collected by the garbage\ncollector. Note that this might be delayed, and that any errors \nwill be disgarded.\n\nIf you are unsure if you have used the correct datatype or want to\ncatch save-errors, use ``save()``::\n\n    group = Group(17)\n    group.accountid = 'itil' # a string won't work in a integer field\n    try:\n        group.save()\n    except Exception, e:\n        print \"Could not save group %s: %s\" % (group, e)\n\nThe exception raised will be database module specific, like\n``psycopg.ProgrammingError``, possible containing some useful information.\n\n``save()`` will return ``True`` if successful.\n\nUndoing an attribute change\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nIf you changed an attribute, and you don't want to save the change to\nthe database (as this will happen when the garbage collector kicks in),\nyou have two choices:\n    \n* reset the instance to a blank state::\n\n     group.reset() \n\n  This sets everything to None, including the primary key. \n  If you have referenced the instance anywhere else, they \n  will now experience a blank instance. \n\n* reload from database::\n\n    group.load()\n\n  Note, ``load()`` will perform a new SELECT.  \n\nNote that you don't have to ``reset()`` if you haven't changed any\nattributes, the instance will only save if anything has changed. \n\n\nAccess foreign keys\n~~~~~~~~~~~~~~~~~~~\n\nExample::\n\n    account = Account(\"stain\")\n    print account.group.accountid\n    print account.group.name\n\nAn attribute which is a foreign key to some other table will be\nidentified by forgetsql-generate if it's name is something like \n``other_table_id``. If the generator could not identify foreign keys\ncorrectly, modify ``_userClasses`` in the generated  Forgetter\ndefinition. (See `Specializing the forgetters`_). \n\nTo access the real primary key, use account.group.accountid or\naccount.group._getID(). Note that the latter will return a tupple\n(in case the primary key contained several columns).o\n\nYou can set a foreign key attribute to a new object from the\nforeign class::\n\n    import random\n    allGroups = Group.getAll()\n    for account in Account.getAll():\n        # Set the group to one of the Group instances\n        # in allGroups\n        account.group = random.choice(allGroups)\n    del account\n    # Note that by reusing the account variable all of these\n    # will be saved by the garbage collector\n\nor to just the foreign primary key::\n\n    account.group = 18\n\nNote that this referencing magic makes JOIN unneccessary in many cases,\nbut be aware that due to lazy loading (attributes are not loaded from\ndatabase before they are accessed for the first time), in some cases\nthis might result in many SELECT-calls. There are ways to avoid this,\nsee `Wrapping SQL queries`_.\n\n\nFinding foreign keys\n~~~~~~~~~~~~~~~~~~~~\n\nYou might want to walk in reverse, finding all accounts that have a\ngiven group as a foreign key::\n\n    group = Group(15)\n    members = group.getChildren(Account)\n\nThis is equivalent to SQL::\n\n    SELECT * FROM account WHERE groupid=15\n\n\nDeleting an instance\n~~~~~~~~~~~~~~~~~~~~\n\nNote that although rows are represented as instances, they will not be\ndeleted from the database by dereferencing. Simply removing a name\nbinding only removes the representation. (and actually forces a \n``save()`` if anything has changed).\n\nTo remove a row from the database::\n    \n    account = Account(\"stornes\")\n    account.delete()\n    \n``delete()`` might fail if your database claims reference integrity but\ndoes not cascade delete::\n\n    group = Group(17)\n    group.delete()\n    \n\nAdvanced use\n------------\n\nWHERE-clasules\n~~~~~~~~~~~~~~\n\nYou may specify a where-sentence to be inserted into the SELECT-call of\n``getAll``-methods::\n\n    members = Account.getAll(where=\"groupid=17\")\n\nNote that you must take care of proper escaping on your own by using\nthis approach. Most database modules have some form of escape functions.\n\nIn many cases, what you want to do with WHERE is probably the\nsame as with ``getChildren()``::\n    \n    group = Group(17)\n    members = group.getChildren(Account)\n\nThis will be as effective as generating a WHERE-clasule, since\n``group.load()`` won't be run (no attributes accessed, only the primary\nkey).\n\nThe sentence is directly inserted, so you need to use the actual SQL\ncolumn names, not the attribute names. You can use AND and OR as you\nlike.\n\nIf you have several clauses to be AND-ed together, forgetSQL can do this\nfor you, as the where-parameter can be a list::\n\n    where = []\n    where.append(\"groupid=17\")\n    if something:\n        where.append(\"fullname like 'Stian%'\")\n    Account.getAll(where=where)\n\n\nSorting\n~~~~~~~\n\nIf you have specified ``_orderBy`` (see `Specializing the forgetters`_),\nthe results of ``getAll*`` and ``getChildren`` will be ordered by those\nattributes. \n\nIf you want to specify ordering manually, you can supply a keyword\nargument to getAll::\n    \n    all = Account.getAll(orderBy=\"fullname\")\n\nThe value of ``orderBy`` could be either a string (representing the\nobject attribute to be sorted) or a tupple of strings (order by A, then\nB, etc.). Note that you can only order by attributes defined in the\ngiven table.    \n    \nIf you want some other fancy sorting, sort the list after retrieval\nusing regular ``list.sort()``::\n\n    all = Account.getAll()\n    all.sort(lambda a,b:\n                cmp(a.split()[-1],\n                    b.split()[-1]))\n    # order by last name! :=)                \n\n\nMore getAll\n~~~~~~~~~~~\n\nThere are specialized ``getAll`` methods for different situations.\n\nIf you just want the IDs in a table::\n\n    >>> all = Account.getAllIDs()\n    ['stornes', 'stain', 'magnun', 'mjaavatt']\n\nThe regular ``getAll()`` actually runs ``getAllIDs()``, and returns a\nlist of instances based on those IDs. The real data is not loaded\nuntil attribute access. In some cases, this might be OK, for instance if\nyou want to call getChildren and really don't care about the attribute\nvalues.\n\nIf you are going to iterate through the list, a common case, use\ninstead::\n\n    for account in Account.getAllIterator():\n        print account.fullname    \n\nThis will return an iterator, not a list, returning ``Account`` objects.\nFor each iteration, a new instance is returned, with all fields\nloaded. Internally in the iterator, a buffer of results from SELECT * is\ncontained.\n\nIn Python, object creation is a bit expensive, so you might reuse the\nsame object for each iteration by creating it first and specifying it \nas the keyword argument ``useObject``::\n\n    for account in Account.getAllIterator(useObject=Account()):\n        print account.fullname\n\nNote that changes made to account in this case will be flushed unless\nyou manually call ``save()``. Do not pass this instance on, as it's content\nwill change for each iteration.\n\nFinally, ``getAllText()`` will use ``_shortView`` (See `Specializing\nthe forgetters`_) and return tupples of (id, text). This is useful for\na dropdown-list of selectors.\n\nSpecializing the forgetters\n---------------------------\n.. About specifying and correcting _sqlFields, etc.\n\nSorry, this section is currently unfinished.\n\nWrapping SQL queries\n--------------------\n.. About joins, views, functions.\n\nSorry, this section is currently unfinished.\n\n\nFramework suggestion\n--------------------\n.. My suggestions for how you should wrap up things nicely, \n.. How to deal with database connections and extensions.\n\nSorry, this section is currently unfinished.\n\n",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "https://github.com/stain/forgetSQL/releases/download/0.5.1/forgetSQL-0.5.1.tar.gz",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/stain/forgetSQL",
        "keywords": "",
        "license": "LGPL 2.1 or later",
        "maintainer": "",
        "maintainer_email": "",
        "name": "forgetSQL",
        "package_url": "https://pypi.org/project/forgetSQL/",
        "platform": "",
        "project_url": "https://pypi.org/project/forgetSQL/",
        "project_urls": {
            "Download": "https://github.com/stain/forgetSQL/releases/download/0.5.1/forgetSQL-0.5.1.tar.gz",
            "Homepage": "https://github.com/stain/forgetSQL"
        },
        "release_url": "https://pypi.org/project/forgetSQL/0.5.1/",
        "requires_dist": null,
        "requires_python": null,
        "summary": "forgetSQL is a Python module for accessing SQL databases by creating",
        "version": "0.5.1"
    },
    "last_serial": 1837485,
    "releases": {
        "0.5.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "ea780a55e89f53da1185a336f04f1401",
                    "sha256": "73bba937b8e2278d2e85df73b8bec66f5375ae8883d926755445827cae409e57"
                },
                "downloads": -1,
                "filename": "forgetSQL-0.5.1.tar.gz",
                "has_sig": true,
                "md5_digest": "ea780a55e89f53da1185a336f04f1401",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 29546,
                "upload_time": "2015-11-28T16:28:26",
                "url": "https://files.pythonhosted.org/packages/2f/08/8fad5c8e2d8ae0460abc9a8d52a8e792f7b39894c03d97de1431ae707c40/forgetSQL-0.5.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "ea780a55e89f53da1185a336f04f1401",
                "sha256": "73bba937b8e2278d2e85df73b8bec66f5375ae8883d926755445827cae409e57"
            },
            "downloads": -1,
            "filename": "forgetSQL-0.5.1.tar.gz",
            "has_sig": true,
            "md5_digest": "ea780a55e89f53da1185a336f04f1401",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 29546,
            "upload_time": "2015-11-28T16:28:26",
            "url": "https://files.pythonhosted.org/packages/2f/08/8fad5c8e2d8ae0460abc9a8d52a8e792f7b39894c03d97de1431ae707c40/forgetSQL-0.5.1.tar.gz"
        }
    ]
}