Difference between revisions of "Silme:Tutorial:Entity"

From Braniecki's Wiki
Jump to navigation Jump to search
 
(4 intermediate revisions by the same user not shown)
Line 8: Line 8:
  
 
<code lang="python">
 
<code lang="python">
from mozilla.l10n.object import Entity
+
from silme.core import Entity
  
 
entity = Entity('id','value')
 
entity = Entity('id','value')
Line 19: Line 19:
  
 
<code lang="python">
 
<code lang="python">
from mozilla.l10n.object import Entity
+
from silme.core import Entity
  
 
entity = Entity('id','value')
 
entity = Entity('id','value')
entity.comment['pre'] = u'Comment prefixing the entity'
 
 
entity.params['author'] = 'Ben'
 
entity.params['author'] = 'Ben'
 
</code>
 
</code>
Line 31: Line 30:
  
 
<code lang="python">
 
<code lang="python">
from mozilla.l10n.object import Entity, EntityList
+
from silme.core import Entity, EntityList
  
entityList = EntityList()
+
entitylist = EntityList()
  
 
entity1 = Entity('example.id','Test value')
 
entity1 = Entity('example.id','Test value')
entityList.addEntity(entity1)
+
entitylist.add_entity(entity1)
  
 
entity2 = Entity('example.id2','Test value2')
 
entity2 = Entity('example.id2','Test value2')
entityList.addEntity(entity2)
+
entitylist.add_entity(entity2, pos=0) # second argument allows you to define on which position an entity should be added
 
</code>
 
</code>
  
Line 45: Line 44:
  
 
<code lang="python">
 
<code lang="python">
from mozilla.l10n.object import EntityList
+
from silme.core import EntityList
  
entityList = EntityList()
+
entitylist = EntityList()
  
entity1 = entityList[0] # returns a first entity from the list
+
entity1 = entitylist[0] # returns a first entity from the list
  
entities = entityList.getEntities() # returns a list of entities
+
entities = entitylist.get_entities() # returns a list of entities
  
entityIdList = entityList.getEntityIds() # returns a list of ids from the entityList
+
entity_id_list = entitylist.get_entity_ids() # returns a list of ids from the entitylist
 
</code>
 
</code>
  
Line 59: Line 58:
  
 
<code lang="python">
 
<code lang="python">
from mozilla.l10n.object import EntityList
+
from silme.core import EntityList
  
entityList = EntityList()
+
entitylist = EntityList()
  
entityList.changeEntity('entity id', 'new value')
+
entitylist.change_entity('entity id', 'new value')
  
entityList.removeEntity('entity id')
+
entitylist.remove_entity('entity id')
 
</code>
 
</code>
  
 
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.
 
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 ==
 
== Example ==
Line 75: Line 76:
  
 
<code lang="python">
 
<code lang="python">
from mozilla.l10n.object import Entity, EntityList
+
from silme.core import Entity, EntityList
  
entityList = EntityList()
+
entitylist = EntityList()
  
 
entity1 = Entity('myproject.id1', 'This is an example message')
 
entity1 = Entity('myproject.id1', 'This is an example message')
Line 83: Line 84:
 
entity2.params['type'] = 'Window title'
 
entity2.params['type'] = 'Window title'
  
entityList.addEntity(entity1)
+
entitylist.add_entity(entity1)
entityList.addEntity(entity2)
+
entitylist.add_entity(entity2)
  
for entity in entityList:
+
for entity in entitylist:
 
   print entity.value
 
   print entity.value
  
entityList.changeEntity('myproject.id1', 'Changed entity')
+
entitylist.change_entity('myproject.id1', 'Changed entity')
entityList.removeEntity('myproject.id1')
+
entitylist.remove_entity('myproject.id1')
 
</code>
 
</code>
  

Latest revision as of 11:54, 13 February 2009

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