Silme:Tutorial:IOClient

As you probably noticed, until now we did not get into any way to actually operate on the l10n objects outside of memory. By this moment you should know how to create an Entity, Comment, how to create an EntityList, L10nObject and L10nPackage and bundle it all together.

Now we'll focus on the ways you can use to load/save those objects to actually be able to use the system in the real life.

There are two levels of this operations. First one is an actual loading entities from somewhere to internal structure like EntityList, L10nObject or L10nPackage and saving it to some place. This is covered by IOClient family.

IOManager

IOManager class is a command center for all kinds of IOClients classes. It means that you should use it to load a proper I/O class. Currently, the project supports several I/O's like file, svn, sqlite, jar.

IOClient

IOClient is an abstract class that is a base for every I/O client that can read and write objects. For example a FileClient can read a file into memory and write it back to the hard drive. Or it can load directory as L10nPackage. SvnClient can load L10nPackage from the directory in SVN repository, JarClient can load a *.jar file as L10nPackage and SQLiteClient can read tables as L10nObjects.

Reading

In the simple case you just use IOManager to load a proper IOClient and then interact with selected type of IO. For example:

import silme.core import silme.io

silme.io.Manager.register('file', 'jar')

ioClient = silme.io.Manager.get('file') # you can you other types here like: jar, sqlite, mysql, svn l10npackage = ioClient.get_l10npackage(path='./test/')


l10nobject = ioClient.get_l10nobject(path='./test/example.dtd')

ioClient2 = silme.io.Manager.get('jar') l10npackage2 = ioClient.get_l10npackage(path='./test.jar')

In result we have two l10nPackages, one from the directory on the hard drive, and another extracted from the .jar file. Also, we have an l10nObject from the hard drive.

Writing

To write down an L10nObject or L10nPackage you simply use the same IOClient:

from mozilla.l10n.object import L10nObject, L10nPackage from mozilla.l10n.io.IOManager import IOManager from mozilla.l10n.io.file import FileClient

ioClient = IOManager.get('file') ioClient.writeL10nPackage(l10nPackage, path='../newpath')

ioClient.writeObject(l10nObject, path='../../example.dtd')

IOClient lets you read and write between the objects in the memory of the program and an actual storage of the data. It may be a database, hard drive, zip package or an RCS.

modifying l10nObject

Thanks to what we already know we can now load an L10nObject, modify it an save back to the file:

from mozilla.l10n.object import L10nObject from mozilla.l10n.io.IOManager import IOManager from mozilla.l10n.io.file import FileClient

file = './test/example.dtd'

ioClient = IOManager.get('file')

l10nObject = ioClient.getL10nObject(path=file) l10nObject.modifyEntity('entity.id', u'new value') ioClient.writeL10nObject(l10nObject, path=file)

This is a very convenient way to work with L10nObjects. You can of course easily operate on all elements of nested L10nPackage structure, modify entities inside and then save the whole package somewhere.

Extended

operating on entities without loading file to memory

In other cases, you may decide that it's not worth loading whole L10nObject to memory just to change/add/remove entity.

For such cases the library offers ability to perform three simple operations on the object in path without loading it to the memory:

from mozilla.l10n.object import L10nObject from mozilla.l10n.io.IOManager import IOManager from mozilla.l10n.io.file import FileClient

file = './test/example.dtd'

ioClient = IOManager.get('file')

(...)

SQLClient specifics

It's important to remember that different kinds of IOClient will give different results. For example SQLClients will not be able to produce full L10nObject and they will serve EntityLists instead.

The reason is that L10nObject is in fact EntityList with a textual context, while SQL does not have any context beside of table rows that represent data.

In most situations you will want to extend the generic SQLClient to suite it to your database structure. You may want to store each locale as a separate column in one table or as a separate table.

RCSClient specifics

In case of RCSCLients their nature requires a user to slightly change the way he operates with the data.

First, while loading L10nObject or L10nPackage, you can select revision from which you want the data to be.

Second, when you save the data, you have to decide how you want the changes to be saves. Should there be a commit on every single change or would you like to offer a user a dynamic sandbox with his changes that are commited once in a while.