File as (Python) Object

Manage a local file as an object. Contents stored in a list.

Written to handle files that contain only text data, good for when you cannot (or will not) use a database.

Typically this module is not appropriate for config files. (Your mileage may vary)

Installation:

pip install fileasobj

Usage:

• See docs/examples.py for lots of useful examples.

# This example adds a line to /etc/hosts

from fileasobj import FileAsObj

my_file = FileAsObj('/etc/hosts')
my_file.add('192.168.0.1  example.org')
my_file.save()

• Depending on your learning style reading tests/tests_fileasobj.py might also be helpful in enabling you to get the most out of this module.

Methods:

• .grep('string')
  • Find all occurrences of string in file.
  • Returns list of matching lines, or returns False if no matches.
• .egrep('^a?regex.*pattern$')
  • Regex-find all occurrences of substring in file.
  • Returns list of matching lines, or returns False if no matches.
  • Uses Python3 standard regex engine https://docs.python.org/3/library/re.html
  • Remember to use ' .* ', not just ' * '.
• .add('entire line as string')
  • Add given line to end of file.
  • Also accepts a list of lines.
• .rm('entire line as string')
  • Remove a line from file, give entire matching line.
  • Also accepts a list of lines.
• .check('entire line as string')
  • Return line if line is in file, else return False
• .read('/path/to/file')
  • Read file into self.contents as list
• .save()
  • Writes contents to file overriding file on disk.
  • Alias of .write()
• .replace('existing line to replace', 'line to use as replacement')
  • Replace a whole line.
  • Will accept a list of lines for first parameter.
• .sort()
  • Sort contents in-place using list()'s sort() method.
• .__str__()
  • If you use a string method on your object (like str() or print()) the contents will be returned as a multi-line string.
  • ex: print(my_file)

Shortcut methods also exist, check examples.py for usage.

Attributes:

• filename
  • String; path to file.
• sorted
  • Boolean; whether to naturally sort contents during update methods. Uses list()'s built-in sort() method.
• unique
  • Boolean; whether to permit duplicate lines during .read() and update methods.
• changed
  • Boolean; whether the current state if different from what was .read() from disk.
  • This is automatically updated during .read() and .write()/.save().
• contents
  • List; contents of file.
• log
  • A string log of all methods run on object including any non-fatal errors
• linesep
  • String; override the default line separator during .write().

An ever-so-slightly-non-apocryphal non-minor version history:

• 2016.04.17 - Conversion and deploy to pypi. FileAsList removed.
• 2015.01.28 - Added shortcut methods, removed exception catching. Added local Log() class.
• 2015.01.27 - .replace() now accepts list for param 'old'.
• 2014.12.02 - Search methods can now return lists and .rm works on lists
• 2014.09.09 - Added .replace(), removed .dump() and .inventory()
• 2014.08.14 - Finally added __str__
• 2014.08.11 - Tab fixes and print changes to comply with py3.
• 2014.06.20 - Added [e]grep, dump and verbose; some code correction
• 2012.08.15 - Full conversion to portability, added .read()
• 2012.07.20 - Initial public release.

Testing:

I write in Python 3.4 and occasionally do testing and 2.7. This module should work with anything between 2.7 and 3.4, please let me know if you find a bug.

./tests/test_fileasobj.py is a standard unit test.

Troubleshooting:

If FileAsObj did something you didn't expect then add a print(my_file.log) to your code, that will show all of the actions FileAsObj took during the object's life.

File an issue on this repo if you need help.

Development & TODO:

• Add as_dict() method: return self.contents as a dictionary, where key is line number and value is line content. Note, there is no use-case for this currently.