Clarify the use of pathnames in the python bindings example scripts

git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@20187 57a11ea4-9604-0410-9ed3-97b8803252fd

src/optional/python-bindings/example_scripts/change_tax_code.py

@@ -27,7 +27,7 @@ def mark_account_with_code_as_tax_related(account, target_code):
         return False
             
 # Change this path to your own
-gnucash_session = Session("xml:///home/mark/python-bindings-help/test.xac")
+gnucash_session = Session("/home/mark/python-bindings-help/test.xac")
 
 mark_account_with_code_as_tax_related(
     gnucash_session.book.get_root_account(),

src/optional/python-bindings/example_scripts/new_book_with_opening_balances.py

@@ -52,18 +52,36 @@ from datetime import date
 #
 # Invocation examples:
 # gnucash-env python new_book_with_opening_balances.py \
-#   'sqlite3:///home/mark/test.gnucash'
+#   '/home/mark/test.gnucash'
 #   'sqlite3:///home/mark/new_test.gnucash'
 #
 # gnucash-env python new_book_with_opening_balances.py \
-#   'sqlite3:///home/mark/test.gnucash' \
-#   'xml:///crypthome/mark/parit-financial-system/new_test.gnucashxml'
+#   '/home/mark/test.gnucash' \
+#   'xml:///crypthome/mark/parit-financial-system/new_test.gnucash'
 #
 # Remember that the gnucash python package has to be in your PYTHONPATH
 # if you're installed GnuCash in a non-standard location, you'll have to do
 # something like this
 # export PYTHONPATH=gnucash_install_path/lib/python2.x/site-packages/
 
+# argv[1] should be the path to an existing gnucash file/database
+# For a file, simply pass the pathname. GnuCash will determine the data format
+# xml or sqlite3 automatically.
+# For a database you can use these forms:
+#   mysql://user:password@host/dbname
+#   postgres://user:password@host[:port]/dbname (the port is optional)
+#
+# argv[2] should be the path for the new gnucash file/database
+# For a file, simply pass the pathname prefixed with the requested data format
+# like:
+#   xml:///home/blah/blah.gnucash
+#   sqlite3:///home/blah/blah.gnucash
+# Paths can also be relative, for example:
+#   xml://from-here/to/there/blah.gnucash
+# For a database you can use these forms:
+#   mysql://user:password@host/dbname
+#   postgres://user:password@host[:port]/dbname (the port is optional)
+
 
 OPENING_DATE = (1, 1, 2011) # day, month, year
 

src/optional/python-bindings/example_scripts/priceDB_test.py

@@ -16,9 +16,16 @@
 #   @ingroup python_bindings_examples
 
 from gnucash import Session
-FILE = "PATH_TO_YOUR_TEST_FILE"  ## Fail is no saved but use a copy anyway
 
-session = Session("xml://%s" % FILE, True, False, False)
+# FILE should be the path to your existing gnucash file/database
+# For a file, simply pass the pathname, for a database you can use
+# these forms:
+# mysql://user:password@host/dbname
+# postgres://user:password@host[:port]/dbname (the port is optional)
+#
+FILE = "PATH_TO_YOUR_TEST_FILE"  ## Fail is not saved but use a copy anyway
+
+session = Session(FILE, True, False, False)
 
 root = session.book.get_root_account()
 book = session.book

src/optional/python-bindings/example_scripts/price_database_example.py

@@ -25,12 +25,11 @@ namespace_name = ""                     # If no namespace_name is set, all names
 show_prices = True                      # If True, all prices for commodity are shown
 commodity_fullname = ""                 # If no name is given, all commoditys in namespace will be shown
 FILE = "PATH_TO_YOUR_TEST_FILE"         # File is not saved but use a copy anyway
-url = "xml://"+FILE
 
 # Configuration end
 # -------------------------------------------
 
-session = Session(url, True, False, False)
+session = Session(FILE, True, False, False)
 
 root = session.book.get_root_account()
 book = session.book

src/optional/python-bindings/example_scripts/simple_book.py

@@ -7,6 +7,7 @@
 import sys
 from gnucash import Session
 
+# We need to tell GnuCash the data format to create the new file as (xml://)
 uri = "xml:///tmp/simple_book.gnucash"
 
 print "uri:", uri

src/optional/python-bindings/example_scripts/simple_business_create.py

@@ -31,6 +31,17 @@
 # employee and vendor, creates an unposted invoice for each,
 # and posts the customer invoice with a few entries and a tax table.
 #
+# argv[1] should be the path the new or to overwrite gnucash file/database
+# for a file, simply pass the pathname prefixed with the requested data format
+# like:
+#   xml:///home/blah/blah.gnucash
+#   sqlite3:///home/blah/blah.gnucash
+# Paths can also be relative, for example:
+#   xml://from-here/to/there/blah.gnucash
+# For a database you can use these forms:
+#   mysql://user:password@host/dbname
+#   postgres://user:password@host[:port]/dbname (the port is optional)
+#
 # You may also want to look at simple_invoice_insert.py
 
 ##  @file

src/optional/python-bindings/example_scripts/simple_invoice_insert.py

@@ -30,8 +30,15 @@
 #
 # Syntax:
 # gnucash-env python simple_invoice_insert.py \
-#          sqlite3:///home/blah/blah.gnucash
-#          dda2ec8e3e63c7715097f852851d6b22 1001 'The Goods' 201.43 
+#          /home/blah/blah.gnucash
+#          dda2ec8e3e63c7715097f852851d6b22 1001 'The Goods' 201.43
+#
+# argv[1] should be the path to an existing gnucash file/database
+# for a file, simply pass the pathname, for a database you can use
+# these forms:
+# mysql://user:password@host/dbname
+# postgres://user:password@host[:port]/dbname (the port is optional)
+#
 
 ##  @file
 #   @brief Add an invoice to a set of books

src/optional/python-bindings/example_scripts/simple_session.py

@@ -13,21 +13,21 @@ FILE_2 = "/tmp/example_file.xac"
 # open a file that isn't there, detect the error
 session = None
 try:
-    session = Session("xml://%s" % FILE_1)
+    session = Session(FILE_1)
 except GnuCashBackendException, backend_exception:
     assert( ERR_FILEIO_FILE_NOT_FOUND in backend_exception.errors)
 
 
-# create a new file
+# create a new file, this requires a file type specification
 session = Session("xml://%s" % FILE_2, is_new=True)
 session.save()
 session.end()
 session.destroy()
 
 # open the new file, try to open it a second time, detect the lock
-session = Session("xml://%s" % FILE_2)
+session = Session(FILE_2)
 try:
-    session_2 = Session("xml://%s" % FILE_2)
+    session_2 = Session(FILE_2)
 except GnuCashBackendException, backend_exception:
     assert( ERR_BACKEND_LOCKED in backend_exception.errors )
 session.end()

src/optional/python-bindings/example_scripts/test_imbalance_transaction.py

@@ -32,8 +32,11 @@ from sys import argv
 from gnucash import Session, Transaction, Split, Account, GncNumeric, \
     GncCommodity
 
-# must be sqlite:///path_to_file or xml:///path_to_file
-# and must be an existing gnucash file
+# argv[1] should be the path to an existing gnucash file/database
+# for a file, simply pass the pathname, for a database you can use
+# these forms:
+# mysql://user:password@host/dbname
+# postgres://user:password@host[:port]/dbname (the port is optional)
 #
 # You should try it out with a gnucash file with tranding accounts enabled
 # and trading accounts disabled