Commits

AJ R committed 2566972

worked on documentation

Comments (0)

Files changed (2)

savReaderWriter/documentation/index.rst

 .. module:: savReaderWriter
    :platform: Linux, Windows, Mac OS, HP-UX, AIX, Solaris, zLinux
    :synopsis: Read/Write SPSS system files (.sav, .zsav)
-.. moduleauthor:: Albert-Jan Roskam <fomcl@yahoo.com>
+.. moduleauthor:: Albert-Jan Roskam
 
 .. _`IBM SPSS Statistics Command Syntax Reference.pdf`: ftp://public.dhe.ibm.com/software/analytics/spss/documentation/statistics/20.0/en/client/Manuals/IBM_SPSS_Statistics_Command_Syntax_Reference.pdf
 .. _`International License Agreement`: ./_static/LA_en
 
     pip install -U -e git+https://bitbucket.org/fomcl/savreaderwriter.git#egg=savreaderwriter
 
+.. versionchanged:: 3.3
+* The ``savReaderWriter`` program now runs on Python 2 and 3. It is tested with Python 2.7 and 3.3.
+It also appears to work with PyPy.
+* ``savReaderWriter`` now uses version 22.0.0.0 of the I/O modules.
+* Several bugs were removed, notably two that prevented the I/O modules from loading in 64-bit Linux and 64-bit Windows systems (NB: these bugs were entirely unrelated). In addition, long variable labels were truncated to 120 characters, which is now fixed.
+
 .. versionchanged:: 3.2
 
 * The ``savReaderWriter`` program is now self-contained. That is, the IBM SPSS I/O modules now all load by themselves, without any changes being required anymore to ``PATH``, ``LD_LIBRARY_PATH`` and equivalents. Also, no extra .deb files need to be installed anymore (i.e. no dependencies). 
 
    :param ioUtf8: Boolean that indicates the mode in which text communicated to or from the I/O Module will  be. Valid values are ``True`` (UTF-8/unicode mode, cf. ``SET UNICODE=ON``) or ``False`` (Codepage mode, ``SET  UNICODE=OFF``) (default: ``False``). 
 
-   :param ioLocale: indicates the locale of the I/O module, cf. ``SET LOCALE`` (default: ``None``, which is the  same as ``".".join(locale.getlocale())``. Locale specification is OS-dependent. in
+   :param ioLocale: indicates the locale of the I/O module, cf. ``SET LOCALE`` (default: ``None``, which is the  same as ``".".join(locale.getlocale())``. Locale specification is OS-dependent. See also under ``SavHeaderReader``.
 
    :param mode: indicates the mode in which <savFileName> should be opened. Possible values are "wb" (write),  "ab" (append), "cp" (copy: initialize header using <refSavFileName> as a reference file, cf. ``APPLY DICTIONARY``). (default: "wb"). 
 
 
 Typical use::
     
-    savFileName = "someFile.sav"
+    savFileName = 'someFile.sav'
     records = [['Test1', 1, 1], ['Test2', 2, 1]]
     varNames = ['var1', 'v2', 'v3']
     varTypes = {'var1': 5, 'v2': 0, 'v3': 0}
 
    :param ioUtf8: Boolean that indicates the mode in which text communicated to or from the I/O Module will be. Valid values are True (UTF-8 mode aka Unicode mode) and False (Codepage mode). Cf. ``SET UNICODE=ON/OFF`` (default = ``False``)
 
-   :param ioLocale: indicates the locale of the I/O module. Cf. ``SET LOCALE`` (default = ``None``, which corresponds to ``".".join(locale.getlocale())``)
+   :param ioLocale: indicates the locale of the I/O module. Cf. ``SET LOCALE`` (default = ``None``, which corresponds to ``".".join(locale.getlocale())``). See also under ``SavHeaderReader``.
 
 .. warning::
 
     data = SavReader(savFileName, idVar="id")
     with data:
         print "The file contains %d records" % len(data)
-        print unicode(data)  # prints a file report
+        print str(data)  # prints a file report
         print "The first six records look like this\n", data[:6]
         print "The first record looks like this\n", data[0]
         print "The last four records look like this\n", data.tail(4)
 
    :param ioUtf8: Boolean that indicates the mode in which text communicated to or from the I/O Module will be. Valid values are ``True`` (UTF-8 mode aka Unicode mode) and ``False`` (Codepage mode). Cf. ``SET UNICODE=ON/OFF`` (default = ``False``)
 
-   :param ioLocale: indicates the locale of the I/O module. Cf. ``SET LOCALE`` (default = ``None``, which corresponds to ``".".join(locale.getlocale())``)
+   :param ioLocale: indicates the locale of the I/O module. Cf. ``SET LOCALE`` (default = ``None``, which corresponds to ``".".join(locale.getlocale())``). Example where this may be needed::
+
+      .. code:: python
+
+         # wrong:  variables are returned as v1, v2, v3
+         >>> with SavHeaderReader('german.sav') as header:
+         ...     print(header.varNames)
+         [b'python', b'programmieren', b'macht', b'v1', b'v2', b'v3']
+         # correct: variable names contain non-ascii characters
+         # locale definition and presence is OS-specific
+         # Linux: sudo localedef -f CP1252 -i de_DE /usr/lib/locale/de_DE.cp1252
+         >>> with SavHeaderReader('german.sav', ioLocale='de_DE.cp1252') as header:
+         ...     print(header.varNames)
+         [b'python', b'programmieren', b'macht', b'\xfcberhaupt', b'v\xf6llig', b'spa\xdf']
 
 .. warning::
 
 
     with SavHeaderReader(savFileName) as header:
         metadata = header.dataDictionary()
-        report = unicode(header)
-        print report 
+        report = str(header)
+        print(report)
 
 .. seealso::
 
 [2] http://docs.python.org/2/library/datetime.html
 [3] ISO 8601 format dates are used wherever possible, e.g. mmddyyyy (``ADATE``) and ddmmyyyy (``EDATE``) is not maintained.
 [4] Months are converted to quarters using a simple lookup table
-[5] weekday, month names depend on host locale (not on ioLocale argument)
+[5] weekday, month names depend on host locale (not on ``ioLocale`` argument)
 
 **Writing dates.** With ``SavWriter`` a Python date string value (e.g. "2010-10-25") can be converted to an SPSS Gregorian date (i.e., just a whole bunch of seconds) by using the ``spssDateTime`` method, e.g.::
 
-    kwargs = dict(savFileName="/tmp/date.sav", varNames=['aDate'], varTypes={'aDate': 0}, formats={'aDate': 'EDATE40'})
+    kwargs = dict(savFileName='/tmp/date.sav', varNames=['aDate'], varTypes={'aDate': 0}, formats={'aDate': 'EDATE40'})
     with SavWriter(**kwargs) as writer:
-        spssDateValue = writer.spssDateTime("2010-10-25", "%Y-%m-%d")
+        spssDateValue = writer.spssDateTime('2010-10-25', '%Y-%m-%d')
         writer.writerow([spssDateValue])
 
 The display format of the date (i.e., the way it looks in the SPSS data editor after opening the .sav file) may be set by specifying the ``formats`` dictionary (see also **Table 1**). This is one of the optional arguments of the ``SavWriter`` initializer. Without such a specification, the date will look like a large integer (the number of seconds since the beginning of the Gregorian calendar).

savReaderWriter/unit_tests/test_SavHeaderReader_ioLocale.py

 class test_SavHeaderReader_ioLocale(unittest.TestCase):
 
     def setUp(self):
-        self.expected = ['python', 'programmieren', 'macht',
-                         '\xfcberhaupt', 'v\xf6llig', 'spa\xdf']
+        self.expected = [b'python', b'programmieren', b'macht',
+                         b'\xfcberhaupt', b'v\xf6llig', b'spa\xdf']
         self.savFileName = "../savReaderWriter/test_data/german.sav"
         self.is_windows = sys.platform.startswith("win")
-	# any locale will do as long as the encoding is cp1252.
+	    # any locale will do as long as the encoding is cp1252.
         # iso-8859-1 and latin-1 will probably also do.
         if self.is_windows:
             self.ioLocale = "German_Germany.1252"
         v1, v2, v3, ..., v<n> because ioLocale is not compatible with file
         locale (codepage). If not specified, ioLocale is initialized to the
         host locale"""
-        wrong = ['python', 'programmieren', 'macht', 'v1', 'v2', 'v3']
+        wrong = [b'python', b'programmieren', b'macht', b'v1', b'v2', b'v3']
         codepage = locale.setlocale(locale.LC_ALL).split(".")[-1]
         incompatible = codepage not in self.ioLocale
         if incompatible:
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.