Note: This documentation is for older version of listorm as 0.x.x

View documentation of listorm after version 1.0

Installation of older version

pip install listorm==0.2.16

import listorm as ls

1-1. Basic useage - create a Listorm Object

1)Listorm Ojbect is derived from list

2)The Elements of Listorm Object is 'Scheme' derived from dict

scheme1 = ls.Scheme({'name': 'park', 'age': 15, 'phone':None})
scheme2 = ls.Scheme({'name': 'kim', 'age':5, 'location': 'Seoul', 'phone': '111-222-333'})

# if add operating smart overwrite (overwrite if value is none on Same key)
scheme1+scheme2

{'age': 15, 'location': 'Seoul', 'name': 'park', 'phone': '111-222-333'}

# The List within different key of dict
lst = [
    {'name': 'Hong', 'age': 18, 'location': 'Korea'},
    {'name': 'Yuki', 'age': 19,},
    {'name': 'Lee', 'age': 12, 'phone': '010-2451-1532'},   
]

# Auto normailize: set same keys for each record(set to None if key does not exists)
ls.Listorm(lst)

[{'age': 18, 'location': 'Korea', 'name': 'Hong', 'phone': None},
 {'age': 19, 'location': None, 'name': 'Yuki', 'phone': None},
 {'age': 12, 'location': None, 'name': 'Lee', 'phone': '010-2451-1532'}]

1-2. Basic useage - retrieve and parsing data

# Customer's info in a Shopping mall
userTable = [
    {'name': 'Hong', 'gender': 'M', 'age': 18, 'location': 'Korea'},
    {'name': 'Charse', 'gender': 'M', 'age': 19, 'location': 'USA'},
    {'name': 'Lyn', 'gender': 'F', 'age': 28, 'location': 'China'},
    {'name': 'Xiaomi', 'gender': 'M', 'age': 15, 'location': 'China'},
    {'name': 'Park', 'gender': 'M', 'age': 29, 'location': 'Korea'},
    {'name': 'Smith', 'gender': 'M', 'age': 17, 'location': 'USA'},
    {'name': 'Lee', 'gender': 'F', 'age': 12, 'location': 'Korea'},
]

#select Columns
lst_customer = ls.Listorm(userTable)
lst_customer.select('name', 'location')

[{'location': 'Korea', 'name': 'Hong'},
 {'location': 'USA', 'name': 'Charse'},
 {'location': 'China', 'name': 'Lyn'},
 {'location': 'China', 'name': 'Xiaomi'},
 {'location': 'Japan', 'name': 'Yuki'},
 {'location': 'Korea', 'name': 'Park'},
 {'location': 'USA', 'name': 'Smith'},
 {'location': 'Korea', 'name': 'Lee'}]

#select Columns only with values, 2dArry
lst_customer = ls.Listorm(userTable)
lst_customer.select('name', 'location', values=True)

[('Hong', 'Korea'),
 ('Charse', 'USA'),
 ('Lyn', 'China'),
 ('Xiaomi', 'China'),
 ('Yuki', 'Japan'),
 ('Park', 'Korea'),
 ('Smith', 'USA'),
 ('Lee', 'Korea')]

#select Columns only with values, Similar to select(*args, values=True)
lst_customer = ls.Listorm(userTable)
lst_customer.row_values('name', 'location')

[['Hong', 'Korea'],
 ['Charse', 'USA'],
 ['Lyn', 'China'],
 ['Xiaomi', 'China'],
 ['Yuki', 'Japan'],
 ['Park', 'Korea'],
 ['Smith', 'USA'],
 ['Lee', 'Korea']]

#filtering
lst_customer = ls.Listorm(userTable)
lst_customer.filter(where=lambda row:row.age > 18)

[{'age': 19, 'gender': 'M', 'location': 'USA', 'name': 'Charse'},
 {'age': 28, 'gender': 'F', 'location': 'China', 'name': 'Lyn'},
 {'age': 19, 'gender': 'F', 'location': 'Japan', 'name': 'Yuki'},
 {'age': 29, 'gender': 'M', 'location': 'Korea', 'name': 'Park'}]

# With Method Chaining
lst_customer = ls.Listorm(userTable)
lst_customer.select('name', 'location', 'age').filter(where=lambda row:row['age'] > 18)

[{'age': 19, 'location': 'USA', 'name': 'Charse'},
 {'age': 28, 'location': 'China', 'name': 'Lyn'},
 {'age': 19, 'location': 'Japan', 'name': 'Yuki'},
 {'age': 29, 'location': 'Korea', 'name': 'Park'}]

# Get a Column values
lst_customer = ls.Listorm(userTable)
lst_customer.column_values('age')

[18, 19, 28, 15, 19, 29, 17, 12]

# Get a Column values unique
lst_customer = ls.Listorm(userTable)
lst_customer.unique('location')

{'China', 'Japan', 'Korea', 'USA'}

# Get a Column values count
lst_customer = ls.Listorm(userTable)
lst_customer.value_count('location')

Counter({'China': 2, 'Japan': 1, 'Korea': 3, 'USA': 2})

2. Basic useage - modifying and update data

# change number type
numbers = [
    {'flt': 0.5, 'string': '123', 'string_float': '123.5', 
     'int': 412, 'string_int': '5123', 'blabla': 'what?'
    }
]

lst_numbers = ls.Listorm(numbers)

# column name and example of types to change, if faild to change, example value will be default value
lst_numbers.set_number_type(flt='', string=0.0, string_float=0, int='', string_int=0, blabla=0)

[{'blabla': 0,
  'flt': '0.5',
  'int': '412',
  'string': 123.0,
  'string_float': 123,
  'string_int': 5123}]

# modify by record qpplied function
lst_customer = ls.Listorm(userTable)
lst_customer.apply_row(
    age= lambda row:'{}_{}'.format(row.gender, row.age),
    name = lambda row:'{}_{}_{}'.format(row.gender, row.age, row.name),
)

[{'age': 'M_18', 'gender': 'M', 'location': 'Korea', 'name': 'M_M_18_Hong'},
 {'age': 'M_19', 'gender': 'M', 'location': 'USA', 'name': 'M_M_19_Charse'},
 {'age': 'F_28', 'gender': 'F', 'location': 'China', 'name': 'F_F_28_Lyn'},
 {'age': 'M_15', 'gender': 'M', 'location': 'China', 'name': 'M_M_15_Xiaomi'},
 {'age': 'F_19', 'gender': 'F', 'location': 'Japan', 'name': 'F_F_19_Yuki'},
 {'age': 'M_29', 'gender': 'M', 'location': 'Korea', 'name': 'M_M_29_Park'},
 {'age': 'M_17', 'gender': 'M', 'location': 'USA', 'name': 'M_M_17_Smith'},
 {'age': 'F_12', 'gender': 'F', 'location': 'Korea', 'name': 'F_F_12_Lee'}]

# modify by value only applied function
lst_customer = ls.Listorm(userTable)
lst_customer.map(gender=lambda val:{'M':'Male', 'F':'Female'}.get(val, val))

[{'age': 18, 'gender': 'Male', 'location': 'Korea', 'name': 'Hong'},
 {'age': 19, 'gender': 'Male', 'location': 'USA', 'name': 'Charse'},
 {'age': 28, 'gender': 'Female', 'location': 'China', 'name': 'Lyn'},
 {'age': 15, 'gender': 'Male', 'location': 'China', 'name': 'Xiaomi'},
 {'age': 19, 'gender': 'Female', 'location': 'Japan', 'name': 'Yuki'},
 {'age': 29, 'gender': 'Male', 'location': 'Korea', 'name': 'Park'},
 {'age': 17, 'gender': 'Male', 'location': 'USA', 'name': 'Smith'},
 {'age': 12, 'gender': 'Female', 'location': 'Korea', 'name': 'Lee'}]

# rename columns
lst_customer = ls.Listorm(userTable)
lst_customer.rename(name='who', location='nation')

[{'age': 18, 'gender': 'M', 'nation': 'Korea', 'who': 'Hong'},
 {'age': 19, 'gender': 'M', 'nation': 'USA', 'who': 'Charse'},
 {'age': 28, 'gender': 'F', 'nation': 'China', 'who': 'Lyn'},
 {'age': 15, 'gender': 'M', 'nation': 'China', 'who': 'Xiaomi'},
 {'age': 19, 'gender': 'F', 'nation': 'Japan', 'who': 'Yuki'},
 {'age': 29, 'gender': 'M', 'nation': 'Korea', 'who': 'Park'},
 {'age': 17, 'gender': 'M', 'nation': 'USA', 'who': 'Smith'},
 {'age': 12, 'gender': 'F', 'nation': 'Korea', 'who': 'Lee'}]

# adding new columns by record applied function
lst_customer = ls.Listorm(userTable)
lst_customer.add_columns(is_child=lambda row:row.age<15).select('name', 'age', 'is_child')

[{'age': 18, 'is_child': False, 'name': 'Hong'},
 {'age': 19, 'is_child': False, 'name': 'Charse'},
 {'age': 28, 'is_child': False, 'name': 'Lyn'},
 {'age': 15, 'is_child': False, 'name': 'Xiaomi'},
 {'age': 19, 'is_child': False, 'name': 'Yuki'},
 {'age': 29, 'is_child': False, 'name': 'Park'},
 {'age': 17, 'is_child': False, 'name': 'Smith'},
 {'age': 12, 'is_child': True, 'name': 'Lee'}]

# get top of records by N
lst_customer = ls.Listorm(userTable)
lst_customer.top('age', n=2) # get oldest 2 people in Listorm

[{'age': 29, 'gender': 'M', 'location': 'Korea', 'name': 'Park'},
 {'age': 28, 'gender': 'F', 'location': 'China', 'name': 'Lyn'}]

# get top of records by percentage(if 0<n<1)
lst_customer = ls.Listorm(userTable)
lst_customer.top('age', n=0.5) # get oldest people by top 50% of age

[{'age': 29, 'gender': 'M', 'location': 'Korea', 'name': 'Park'},
 {'age': 28, 'gender': 'F', 'location': 'China', 'name': 'Lyn'},
 {'age': 19, 'gender': 'M', 'location': 'USA', 'name': 'Charse'},
 {'age': 19, 'gender': 'F', 'location': 'Japan', 'name': 'Yuki'}]

3 . Advanced useage - sorting, grouping, join

# 1.orderby location ASC age DESC
lst_customer = ls.Listorm(userTable)
lst_customer.orderby('location', '-age')

[{'age': 28, 'gender': 'F', 'location': 'China', 'name': 'Lyn'},
 {'age': 15, 'gender': 'M', 'location': 'China', 'name': 'Xiaomi'},
 {'age': 19, 'gender': 'F', 'location': 'Japan', 'name': 'Yuki'},
 {'age': 29, 'gender': 'M', 'location': 'Korea', 'name': 'Park'},
 {'age': 18, 'gender': 'M', 'location': 'Korea', 'name': 'Hong'},
 {'age': 12, 'gender': 'F', 'location': 'Korea', 'name': 'Lee'},
 {'age': 19, 'gender': 'M', 'location': 'USA', 'name': 'Charse'},
 {'age': 17, 'gender': 'M', 'location': 'USA', 'name': 'Smith'}]

# 2-1groupby location, retrieve gender count and max age
lst_customer = ls.Listorm(userTable)
lst_customer.groupby('location', age=max, gender=len)

[{'age': 28, 'gender': 2, 'location': 'China'},
 {'age': 19, 'gender': 1, 'location': 'Japan'},
 {'age': 29, 'gender': 3, 'location': 'Korea'},
 {'age': 19, 'gender': 2, 'location': 'USA'}]

# 2-2.you can rename retrieving columns name which set by grouped result 
lst_customer = ls.Listorm(userTable)
lst_customer.groupby('location', 
            age=max, gender=len, location=len, 
            renames={'age':'Oldest', 'gender': 'GenderCount', 'location': 'locationCount'}
    )

[{'GenderCount': 2, 'Oldest': 28, 'locationCount': 2},
 {'GenderCount': 1, 'Oldest': 19, 'locationCount': 1},
 {'GenderCount': 3, 'Oldest': 29, 'locationCount': 3},
 {'GenderCount': 2, 'Oldest': 19, 'locationCount': 2}]

# 2-2.you can include extra column value(value might be last record of group)
lst_customer = ls.Listorm(userTable)
lst_customer.groupby('location',
            age=max, gender=len, location=len, 
            renames={'age':'Oldest', 'gender': 'GenderCount', 'location': 'locationCount'},
            extra_columns = ['location']
    )

[{'GenderCount': 2, 'Oldest': 28, 'location': 'China', 'locationCount': 2},
 {'GenderCount': 1, 'Oldest': 19, 'location': 'Japan', 'locationCount': 1},
 {'GenderCount': 3, 'Oldest': 29, 'location': 'Korea', 'locationCount': 3},
 {'GenderCount': 2, 'Oldest': 19, 'location': 'USA', 'locationCount': 2}]

# 3.join
#Customers buy records for join Example
buyTable = [
    {'name': 'Xiaomi', 'product': 'battery', 'amount':7},
    {'name': 'Hong', 'product': 'keyboard', 'amount':1},
    {'name': 'Lyn', 'product': 'cleaner', 'amount':5},
    {'name': 'Hong', 'product': 'monitor', 'amount':1},
    {'name': 'Hong', 'product': 'mouse', 'amount':3},
    {'name': 'Lyn', 'product': 'mouse', 'amount':1},
    {'name': 'Unknown', 'product': 'keyboard', 'amount':1},
    {'name': 'Lee', 'product': 'hardcase', 'amount':2},
    {'name': 'Lee', 'product': 'keycover', 'amount':2},
    {'name': 'Yuki', 'product': 'manual', 'amount':1},
    {'name': 'Xiaomi', 'product': 'cable', 'amount':1},
    {'name': 'anonymous', 'product': 'adopter', 'amount':2},
    {'name': 'Park', 'product': 'battery', 'amount':2},
    {'name': 'Hong', 'product': 'cleaner', 'amount':3},
    {'name': 'Smith', 'product': 'mouse', 'amount':1},
]

lst_customer = ls.Listorm(userTable)
lst_buyitems = ls.Listorm(buyTable)

# 3-1 inner join
# Add Extra customer's Info (location) to each buytime
lst_buyitems.join(lst_customer.select('location', 'name'), on='name')

[{'amount': 1, 'location': 'Japan', 'name': 'Yuki', 'product': 'manual'},
 {'amount': 1, 'location': 'USA', 'name': 'Smith', 'product': 'mouse'},
 {'amount': 2, 'location': 'Korea', 'name': 'Lee', 'product': 'hardcase'},
 {'amount': 2, 'location': 'Korea', 'name': 'Lee', 'product': 'keycover'},
 {'amount': 7, 'location': 'China', 'name': 'Xiaomi', 'product': 'battery'},
 {'amount': 1, 'location': 'China', 'name': 'Xiaomi', 'product': 'cable'},
 {'amount': 1, 'location': 'Korea', 'name': 'Hong', 'product': 'keyboard'},
 {'amount': 1, 'location': 'Korea', 'name': 'Hong', 'product': 'monitor'},
 {'amount': 3, 'location': 'Korea', 'name': 'Hong', 'product': 'mouse'},
 {'amount': 3, 'location': 'Korea', 'name': 'Hong', 'product': 'cleaner'},
 {'amount': 2, 'location': 'Korea', 'name': 'Park', 'product': 'battery'},
 {'amount': 5, 'location': 'China', 'name': 'Lyn', 'product': 'cleaner'},
 {'amount': 1, 'location': 'China', 'name': 'Lyn', 'product': 'mouse'}]

# 3-2 left join
# if names in buy table are not in customer table, then set to none the customer's info(location is set to none)
lst_buyitems.join(lst_customer.select('location', 'name'), on='name', how='left')
# Unknown and anonymouse location would be set to None

[{'amount': 1, 'location': 'Korea', 'name': 'Hong', 'product': 'keyboard'},
 {'amount': 1, 'location': 'Korea', 'name': 'Hong', 'product': 'monitor'},
 {'amount': 3, 'location': 'Korea', 'name': 'Hong', 'product': 'mouse'},
 {'amount': 3, 'location': 'Korea', 'name': 'Hong', 'product': 'cleaner'},
 {'amount': 2, 'location': 'Korea', 'name': 'Lee', 'product': 'hardcase'},
 {'amount': 2, 'location': 'Korea', 'name': 'Lee', 'product': 'keycover'},
 {'amount': 5, 'location': 'China', 'name': 'Lyn', 'product': 'cleaner'},
 {'amount': 1, 'location': 'China', 'name': 'Lyn', 'product': 'mouse'},
 {'amount': 2, 'location': 'Korea', 'name': 'Park', 'product': 'battery'},
 {'amount': 1, 'location': 'USA', 'name': 'Smith', 'product': 'mouse'},
 {'amount': 1, 'location': None, 'name': 'Unknown', 'product': 'keyboard'},
 {'amount': 7, 'location': 'China', 'name': 'Xiaomi', 'product': 'battery'},
 {'amount': 1, 'location': 'China', 'name': 'Xiaomi', 'product': 'cable'},
 {'amount': 1, 'location': 'Japan', 'name': 'Yuki', 'product': 'manual'},
 {'amount': 2, 'location': None, 'name': 'anonymous', 'product': 'adopter'}]

# 3-3 outer join
lst_buyitems.join(lst_customer.select('location', 'name'), on='name', how='outer')

[{'amount': None, 'location': 'USA', 'name': 'Charse', 'product': None},
 {'amount': 1, 'location': 'Japan', 'name': 'Yuki', 'product': 'manual'},
 {'amount': 1, 'location': 'USA', 'name': 'Smith', 'product': 'mouse'},
 {'amount': 2, 'location': 'Korea', 'name': 'Lee', 'product': 'hardcase'},
 {'amount': 2, 'location': 'Korea', 'name': 'Lee', 'product': 'keycover'},
 {'amount': 7, 'location': 'China', 'name': 'Xiaomi', 'product': 'battery'},
 {'amount': 1, 'location': 'China', 'name': 'Xiaomi', 'product': 'cable'},
 {'amount': 1, 'location': None, 'name': 'Unknown', 'product': 'keyboard'},
 {'amount': 1, 'location': 'Korea', 'name': 'Hong', 'product': 'keyboard'},
 {'amount': 1, 'location': 'Korea', 'name': 'Hong', 'product': 'monitor'},
 {'amount': 3, 'location': 'Korea', 'name': 'Hong', 'product': 'mouse'},
 {'amount': 3, 'location': 'Korea', 'name': 'Hong', 'product': 'cleaner'},
 {'amount': 2, 'location': None, 'name': 'anonymous', 'product': 'adopter'},
 {'amount': 2, 'location': 'Korea', 'name': 'Park', 'product': 'battery'},
 {'amount': 5, 'location': 'China', 'name': 'Lyn', 'product': 'cleaner'},
 {'amount': 1, 'location': 'China', 'name': 'Lyn', 'product': 'mouse'}]

4-1.Utilities - Find Different in two different table - The Changed thing in table

# changing to add two record, delete two record and modified a recored where name ==Lyn set age 28 
before = [
    {'name': 'Hong', 'gender': 'M', 'age': 18, 'location': 'Korea'},
    {'name': 'Charse', 'gender': 'M', 'age': 19, 'location': 'USA'},
    {'name': 'Lyn', 'gender': 'F', 'age': 29, 'location': 'China'},
]
after = [
    {'name': 'Lyn', 'gender': 'F', 'age': 28, 'location': 'China'},
    {'name': 'Xiaomi', 'gender': 'M', 'age': 15, 'location': 'China'},
    {'name': 'Park', 'gender': 'M', 'age': 29, 'location': 'Korea'},
]

changes = ls.Listorm(before).get_changes(after, pk='name')
#pk: primary key is needed

changes

Changes(added=[Added(pk='Xiaomi', rows={'location': 'China', 'gender': 'M', 'name': 'Xiaomi', 'age': 15}), Added(pk='Park', rows={'location': 'Korea', 'gender': 'M', 'name': 'Park', 'age': 29})], deleted=[Deleted(pk='Hong', rows={'location': 'Korea', 'gender': 'M', 'name': 'Hong', 'age': 18}), Deleted(pk='Charse', rows={'location': 'USA', 'gender': 'M', 'name': 'Charse', 'age': 19})], updated=[Updated(pk='Lyn', before={'location': 'China', 'gender': 'F', 'name': 'Lyn', 'age': 29}, after={'location': 'China', 'gender': 'F', 'name': 'Lyn', 'age': 28}, where=['age'])])

changes.added

[Added(pk='Xiaomi', rows={'location': 'China', 'gender': 'M', 'name': 'Xiaomi', 'age': 15}),
 Added(pk='Park', rows={'location': 'Korea', 'gender': 'M', 'name': 'Park', 'age': 29})]

changes.deleted

[Deleted(pk='Hong', rows={'location': 'Korea', 'gender': 'M', 'name': 'Hong', 'age': 18}),
 Deleted(pk='Charse', rows={'location': 'USA', 'gender': 'M', 'name': 'Charse', 'age': 19})]

changes.updated

[Updated(pk='Lyn', before={'location': 'China', 'gender': 'F', 'name': 'Lyn', 'age': 29}, after={'location': 'China', 'gender': 'F', 'name': 'Lyn', 'age': 28}, where=['age'])]

4-2. Utilities - Read And Write to Excel, CSV

lst = ls.read_excel(file_name=None, file_contents=None, sheet_index=0, start_row=0, index=None)

Excel File or byte Content of Excel to Listorm object

lst = ls.read_csv(filename=None, encoding='utf-8', fp=None, index=None)

CSV file or filepointer of CSV to Listorm object

# saving date to excel or CSV
lst_customer = ls.Listorm(userTable)
excel_file_content = lst_customer.to_excel(filename=None) # If filnames is None, returns bytes of filecontents
csv_file_content = lst_customer.to_csv(filename=None) # If filnames is None, returns bytes of filecontents

listorm

listorm