Silme:Tutorial:Entity

Entity

The basic unit we use in the localization world is an entity. Entity is a simple object made of ID and a value. ID is a somehow unique identifier of the entity, and the value is an actual string that you want to present to the user.

In Verbatim creating a new Entity looks like this:

 from silme.core import Entity
 
 entity = Entity('id','value')

This simple object is the most atomic unit in every localization format, be it DTD, Gettext, XLIFF or L20n. It's an abstract representation of a row in the l10n array in SQL or it represents a single string in HTML file (in this case ID has to be a unique identifier of the string position in the file).

Of course Entity may be much more complex than that. In some cases you can have a meta data for the single entity, or a comment that is tied to the entity. Because of how popular those two cases are among l10n formats, Entity object has predefined dictionary objects for those two:

 from silme.core import Entity
 
 entity = Entity('id','value')
 entity.params['author'] = 'Ben'

EntityList

EntityList is a simplest possible class used to store the sequence of entities.

 from silme.core import Entity, EntityList
 
 entitylist = EntityList()
 
 entity1 = Entity('example.id','Test value')
 entitylist.add_entity(entity1)
 
 entity2 = Entity('example.id2','Test value2')
 entitylist.add_entity(entity2, pos=0) # second argument allows you to define on which position an entity should be added

You can operate on the EntityList to get either all Entities as a new list or just ids of the entities as a new list

 from silme.core import EntityList
 
 entitylist = EntityList()
 
 entity1 = entitylist[0] # returns a first entity from the list
 
 entities = entitylist.get_entities() # returns a list of entities
 
 entity_id_list = entitylist.get_entity_ids() # returns a list of ids from the entitylist

If you want, you can also change entity or remove it:

 from silme.core import EntityList
 
 entitylist = EntityList()
 
 entitylist.change_entity('entity id', 'new value')
 
 entitylist.remove_entity('entity id')

You may assume that the functionality of the Entity and EntityList classes is very basic. Later you'll notice that it makes the use of the library much easier.

An important difference between having a list of Entity objects and having an EntityList object is that in case of EntityList you may define parameters that are defined for the whole list. Another reason is that you may use, and it's preferred, a set of methods to manipulate on the list instead of touching the list directly. The last one is that your code will stay untouched if we'll switch to dictionary as a base class for EntityList in the future.

Example

Below is a bit more complex example of using those two classes

 from silme.core import Entity, EntityList
 
 entitylist = EntityList()
 
 entity1 = Entity('myproject.id1', 'This is an example message')
 entity2 = Entity('myproject.title', 'App title')
 entity2.params['type'] = 'Window title'
 
 entitylist.add_entity(entity1)
 entitylist.add_entity(entity2)
 
 for entity in entitylist:
     print entity.value

 entitylist.change_entity('myproject.id1', 'Changed entity')
 entitylist.remove_entity('myproject.id1')

Advanced topics

You may decide to extend Entity class or just add your own properties to the Entity object.

It would benefit performance and code sleekness to assume that the ID is unique across an EntityList, but the reality is different