Address book of the CEOs of technology companies

The following illustrates a schema for an address book of people, the companies that they work for, and their addresses, and an example address book of the CEOs of several technology companies.

Address books are represented using three classes to represent people (Person), the companies that they work for (Company), and their addresses (Address).

The many-to-one relationship between companies and their employees (Person.company) and the one-to-one relationships between company and people and their addresses (Company.address, Person.address) are represented by ManyToOne and OneToOne attributes. The required argument related_name defines the name of the reverse relationship from the related class (Company.employees, Address.company, Address.person). This makes each relationship bidirectional.

Address books are encoded into two worksheets for companies and their employees, with groups of columns that represent the address of each company and employee. Encoding companies and their addresses and people and their addresses into the same worksheet, rather than encoding addresses into a separate worksheet, makes address books easier for human to read.

The ObjTables software provides an object-relational mapping system (ORM) that can automatically map between the object-oriented and spreadsheet representations. This makes it easy for authors to create datasets with high-level data structures and export them to human-readable spreadsheets, and this makes it easy for other investigators to parse human-readable spreadsheets into convenient data structures for comparison and re-analysis. Similar to other ORMs, ObjTables makes it easy to define constraints on the value of each attribute (e.g., an attribute that represents molecular weights must be positive), ObjTables makes it easy to implement custom validations of each object and entire datasets, and ObjTables automatically generates APIs for constructing objects and querying their relationships. See below for more information.

Tabular-formatted schema

A more complete example is available in TSV format from GitHub .

Schema defined as a Python module

A more complete example is available in Python format from GitHub .

import obj_tables

class Address(obj_tables.Model):
    street = obj_tables.StringAttribute(
        primary=True,
        unique=True,
        verbose_name='Street')
    city = obj_tables.StringAttribute(
        verbose_name='City')
    state = obj_tables.StringAttribute(
        verbose_name='State')
    zip_code = obj_tables.StringAttribute(
        verbose_name='Zip code')
    country = obj_tables.StringAttribute(
        verbose_name='Country')

    class Meta(obj_tables.Model.Meta):
        table_format = \
            obj_tables.TableFormat \
                .multiple_cells
        attribute_order = (
            'street',
            'city',
            'state',
            'zip_code',
            'country',
        )
        verbose_name = 'Address'
        verbose_name_plural = 'Addresses'

class PersonType(enum.Enum):
    family = 'family'
    friend = 'friend'
    business = 'business'

class Person(obj_tables.Model):
    name = obj_tables.StringAttribute(
        primary=True,
        unique=True,
        verbose_name='Name')
    type = obj_tables.EnumAttribute(
        PersonType,
        verbose_name='Type')
    company = obj_tables.ManyToOneAttribute(
        'Company',
        related_name='employees',
        verbose_name='Company')
    email_address = obj_tables.EmailAttribute(
        verbose_name='Email address')
    phone_number = obj_tables.StringAttribute(
        verbose_name='Phone number')
    address = obj_tables.OneToOneAttribute(
        'Address',
        related_name='person',
        verbose_name='Address')

    class Meta(obj_tables.Model.Meta):
        table_format = \
            obj_tables.TableFormat.row
        attribute_order = (
            'name',
            'type',
            'company',
            'email_address',
            'phone_number',
            'address',
        )
        verbose_name = 'Person'
        verbose_name_plural = 'People'


class Company(obj_tables.Model):
    name = obj_tables.StringAttribute(
        primary=True,
        unique=True,
        verbose_name='Name')
    url = obj_tables.UrlAttribute(
        verbose_name='URL')
    address = obj_tables.OneToOneAttribute(
        'Address',
        related_name='company',
        verbose_name='Address')

    class Meta(obj_tables.Model.Meta):
        table_format = \
            obj_tables.TableFormat.row
        attribute_order = (
            'name',
            'url',
            'address',
        )
        verbose_name = 'Company'
        verbose_name_plural = 'Companies'

Tabular-formatted dataset

The following example illustrates an address book of the CEOs of several major technology companies, the companies that they lead, and their addresses. A more complete example is available in merged-TSV format from GitHub .

Download additional examples

Tabular format for schemas

Tabular-formatted schemas should begin with a single header row, which indicates that the schema is encoded in ObjTables format (!!ObjTables type="Schema" ...).

Optionally, the header can use the name attribute to define the name of the schema (e.g., !!ObjTables type="Schema" name="<schema-name>" ...). If worksheets also define the schema that they belong to, ObjTables will check that these values are equal.

After the header row, the schema should contain a table with the columns below that defines the classes/models/tables and their attributes/columns. Each row in the table should define a single class or attribute.

• !Name: Name of the component (class or attribute).
  • Classes: A string that begins with a letter or underscore, and consists of letters, numbers, and underscores.
  • Attributes: A string that begins with a letter or underscore, and consists of letters, numbers, underscores, colons, forward carets, dots, dashes, square brackets, and spaces.
• !Type: Type of the component (Class or Attribute).
• !Parent:
  • Classes: Empty, or the name of the parent class. Because this is implemented using Python class inheritance, this must specify an acyclic inheritance graph.
  • Attributes: Name of the class that the attribute belongs to.
• !Format:
  • Classes:
    • row: Encode the instances of the class as rows.
    • column: Encode the instances of the class as columns (i.e., transposed table).
    • multiple_cells: Encode the instances of the class within a group of columns in the tables of the one-to-many and one-to-one related classes.
    • cell: Encode the instances of the class within columns of the related classes, optionally, using a grammar. See the Python documentation for more information about working with grammars.
  • Attributes: One of the data types listed below (e.g., String, Float). Arguments for the data types should be described in parentheses (e.g., String(min_length=5). These arguments enable users to customize how data types function and are validated. See the Python documentation for more information about the attribute types and their arguments.
• !Verbose name (Optional): Verbose name of the component.
• !Verbose name plural (Optional): Plural verbose name of the component.
• !Description (Optional): Description of the component.

Tabular-formatted schemas can be saved in comma-separated (.csv), tab-separated (.tsv), or XSLX (.xlsx) format.

Implementing schemas in Python using the Python package

Schemas can also be implemented using the ObjTables Python package. The API enables developers to define schemas with a similar syntax to object-relational mapping tools such as Django , Ruby on Rails , and SQLAlchemy .

• The name of the schema is given by the name of the Python module which encapsulates the schema. Typically, this the filename of the module.
• Each class should be implemented as a subclass of obj_tables.Model.
• Each attribute of each class should be implemented as a class attribute whose value is an instance of a subclass of obj_tables.Attribute. Numerous subclasses of obj_tables.Attribute, which support a wide range of data types, are available. Please see below and the Python documentation for more information, including the arguments of these classes.
  • Each relationship between two classes should be implemented using the obj_tables.OneToOneAttribute, obj_tables.OneToManyAttribute, obj_tables.ManyToOneAttribute, or obj_tables.ManyToManyAttribute classes.
• The meta-information about each class, such as its verbose name, should be implemented as a class attribute with the name Meta that is a subclass of obj_tables.Model.Meta. This class can have the following class attributes:
  • unique_together: Tuple of tuples of the names of attributes whose values must be unique.
  • verbose_name: Verbose name of the class.
  • verbose_name_plural: Plural verbose name of the class.
  • description: Description of the class.
  • table_format: Indicates how the class should be formatted: obj_tables.TableFormat.row (normal table), obj_tables.TableFormat.column (transposed table), obj_tables.TableFormat.multiple_cells (inline as a set of columns/rows within the tables of related classes), or obj_tables.TableFormat.cell (inline encoded into a column or row of the tables of the related classes).
  • attribute_order: List of the names of the attributes of the class in the order they should be printed in its table.
  • ordering: Defines the default sorting for the instances of the class. This should be a list of strings of the names of attributes, in the order in which the values of the attributes should be sorted. Optionally, the prefix - can be used to indicate that instances should be sorted in reverse order of the values of the attribute.
  • frozen_columns: Number of columns to freeze when the class is printed to an XLSX worksheet.
  • merge: Indicates how semantically-equivalent instances of the class should be merged when two datasets are merged: obj_tables.ModelMerge.join (concatenate their *-to-many relationships) or obj_tables.ModelMerge.append (throw an error if datasets contain semantically equivalent instances).

Please see the Python documentation for more information.

Encoding multiple classes into a single table

To encode complex datasets into a minimal number of tables, related classes can be encoded into a column or a series of columns of the table that represents their (row-formatted) parent classes. (For column-formatted parent classes, related classes can be encoded into a row or a series of rows.)

• Classes related by *-to-one attributes:
  • For row-formatted classes, classes related by *-to-one attributes can be encoded into a series of consecutive columns by setting the formats of the related classes to multiple_cells in the schema. When this feature is used, tables must include an additional row of column headings which indicate the groups of columns.
  • For column-formatted classes, classes related by *-to-one attributes can be encoded into a series of consecutive rows by setting the formats of the related classes to multiple_cells in the schema. When this feature is used, tables must include an additional column of row headings which indicate the groups of columns.
• Classes related by a ToManyGrammar attribute:
  • For row-formatted classes, such related classes can be encoded into a column by setting the formats of the related classes to cell in the schema.
  • For column-formatted classes, such related classes can be encoded into a row by setting the formats of the related classes to cell in the schema.

ObjTables supports numerous data types, and it is easy to implement additional types.

This includes powerful data types from several mathematics and science packages:

• BioPython : sequence informatics
• lark : grammars for describing complex relationships
• numpy : numeric arrays
• pandas : data tables
• pint : units
• sympy : symbolic math
• uncertainties : values and their uncertainty

The following table lists the attribute types currently available in ObjTables. The first column indicates the names that should be used in conjunction with the tabular schema format. The second column indicates the Python class which implements each type, and which should be used to define schemas with the Python package. The third column indicates the data type used to encode each attribute into an spreadsheet cell. The fourth column indicates the Python data type used to represent each attribute in the ObjTables software tools.

Required arguments

A few of the attributes have required arguments. Please see the Python documentation for more information.

• Enum attribute: The first argument must be a subclass of enum.Enum or a list of the enumerated values. For example, an enumerated attribute with two potential values 'A' and 'B' can be specified in the tabular schema format using the syntax Enum(['A', 'B']).
• *To* attributes: The first argument must be a class or the name of a class. The constructor must also receive a keyword argument with the key related_name whose value is a string that represents the name of a virtual property that should be added to the related class to represent pointers from the related objects back to the primary objects. For example, an attribute with the name parents which represents a many-to-many relationship from a class Child that represents children to a class Parent that represents their parents and contains a virtual attribute children that represents the inverse many-to-many relationship can be specified in the tabular schema format using the syntax ManyToMany('Parent', related_name='children').
• ToManyGrammar attributes: The first argument must be a class or the name of a class. The constructor must also receive a keyword argument with the key grammar whose argument is a string that defines the grammar or is the path to a file that defines the grammar. The grammar must be defined using Lark's EBNF syntax . In addition, Python developers can customize how data encoded into a grammar is transformed into class instances and attributes by (1) creating a subclass of obj_tables.ToManyGrammar and (2) setting its Transformer attribute to a subclass of obj_tables.ToManyGrammarTransformer. Please see the Python documentation for more information.

Optional arguments

Most of the attributes also have optional arguments that can be used to control how values of the attribute are validated. For example, the Integer and Float attributes have optional min and max arguments which can be used to indicate the minimum and maximum valid values. The String and LongString attributes have optional min_length and max_length attributes which can be used to indicate the minimum and maximum valid lengths of each value.

Specifying required and optional attributes

The none argument controls whether an attribute is required (its value must be defined) or optional (its value can be undefined – null in XLSX, null in JSON and YAML, None in Python):

• none=False means that the value of an attribute must be defined. This makes an attribute required.
• none=True means that the value of an attribute can be undefined. This makes an attribute optional.

Specifying that an attribute can function as a foreign key for encoding relationships with instances of other classes into tables

The unique and primary arguments can be used to configure attributes to function as primary keys for encoding relationships between instances of classes into tables:

• unique: Set this argument to True to indicate that ObjTables should constrain the values of the attribute to be unique across all instances of its parent class.
• primary: Set this argument to True to indicate that the attribute is the primary key for its parent class. Each class can only have one primary attribute, and primary attributes should also have unique = True.

More information about the arguments

Please see the Python documentation for detailed information about these required and optional arguments.

ObjTables can encode and decode datasets into and from the file formats outlined below. We recommend using programs such as Microsoft Excel or LibreOffice Calc for viewing and editing datasets. We recommend using CSV or TSV to store datasets because these formats are conducive to revisioning with version control systems such as Git. We recommend using JSON for working with ObjTables in other programming languages beyond Python.

• Tabular formats: Collections of tables in comma-separated (CSV), tab-separated (TSV), or XLSX format.
  • Set of CSV or TSV files (.csv, .tsv)
    • Each tabular file represents the instances of a class (and possibly related instances of other classes).
    • The names of the files should follow the pattern *.{csv,tsv} (e.g., Name.csv).
    • As described below, the table in each file should be proceeded by a line that begins with !!ObjTables id="TableName" ... that declares that ObjTables should process the table in the file. This declaration can also contain metadata about the following table.
    • ObjTables ignores files that do not contain this declaration. This can be used to store additional metadata alongside a dataset.
    • Sets of CSV and TSV files can be uploaded to the web application as a zip archive.
    • ObjTables uses the Excel dialect of the CSV and TSV formats .
  • Single text file which contains multiple CSV or TSV-formatted tables (.multi.csv, .multi.tsv)
    • This format is similar to a set of CSV or TSV files, except that the tables are concatenated into a single file.
    • The beginning of each table (and the end of the previous table) is indicated by the !!ObjTables id="TableName" ... declarations.
  • XLSX workbook (.xlsx)
    • Open standard: ECMA-376 , ISO/IEC 29500 .
    • This format is also similar to a set of CSV or TSV files, except that each table is contained in a worksheet in a workbook rather than in a separate text file.
    • The title of each worksheet should be !! followed by the name of the class in the schema (e.g., !!Name) encoded into the worksheet.
    • Optionally, workbooks can include a table of contents worksheet that summarizes and provides hyperlinks to the data tables. This should have the title !!_Table of contents.
    • Optionally, workbooks can include a worksheet that describes the schema of the dataset. This should have the title !!_Schema.
    • The ObjTables software tools can generate these optional table of contents and schema worksheets.
    • Workbooks can contain additional worksheets whose names do not begin with !!. These worksheets will be ignored by ObjTables. This can be used to store additional metadata alongside a dataset.
• Data serialization formats: Serialization of ObjTables' internal data structures. See below for more information about using these formats in other languages.
  • JavaScript Object Notation (.json)
  • YAML Ain't Markup Language (.yml)

Tabular format for datasets

Dataset/document declaration: declaring that a collection of tables is encoded in ObjTables' tabular format

Each collection of tables must declare that the tables are encoded in ObjTables's tabular format by including the line !!!ObjTables ... before one of the tables.

Dataset/document-level metadata

Optionally, document declarations (!!!ObjTables ...) can capture key-value pairs of document-level metadata. Each key and value should be a string. At a minimum, we recommend using the keys below. The ObjTables software automatically generates these keys when datasets are exported to files.

• id: Use this key to provide a unique identifier for the dataset.
• schema: Use this key to annotate the name of the schema of the dataset. If this key is set, ObjTables will check that its value matches the name of the schema used to interpret the dataset. The name of tabular-formatted schemas can be declared using the name meta attribute (e.g., !!ObjTables type="Schema" name="<schema-name>" ...). The name of Python-defined schemas is the name of the module which implements the schema, which is typically the filename of the module.
• date: Use this key to annotate the date that the dataset was created or updated.
• objTablesVersion: Use this key to indicate the version of the ObjTables tabular format used to encode the dataset.

Class/table declaration: declaring the class represented by each table

Each table must declare the class that it represents by including a line that begins with !!ObjTables type='Data' class='<class_name>' ...). The value of class should be the name of a class in the schema.

Class/table-level metadata

Optionally, table declarations can capture key-value pairs of class/table-level metadata. Each key and value should be a string. At a minimum, we recommend using the keys below. The ObjTables software automatically generates these keys when datasets are exported to files.

• document: Use this key to annotate the id of the parent document.
• schema: Use this key to annotate the name of the schema of the table. If this key is set, ObjTables will check that its value matches the name of the schema used to interpret the table. The name of tabular-formatted schemas can be declared using the name meta attribute (e.g., !!ObjTables type="Schema" name="<schema-name>" ...). The name of Python-defined schemas is the name of the module which implements the schema, which is typically the filename of the module.
• tableFormat: Use this key to indicate the format (row, column, multiple_cells, or cell) used to encode the class into the table. See above for more information about these formats. If this key is set, ObjTables will check that its value matches the format for the class defined in the schema.
• name: Use this key to briefly describe the class.
• description: Use this key to capture an extended description of the class.
• date: Use this key to annotate the date that the table was created or updated.
• objTablesVersion: Use this key to indicate the version of the ObjTables tabular format used to encode the class.

Class attribute declaration: declaring the attribute represented by each entry of each table

• row-formatted classes: After the class/table declaration, the cells in the first row of the table should declare the attributes represented by each column. Each cell should begin with ! followed by the name of the attribute as defined in the schema (e.g., !Id).
• column-formatted classes: Similarly, after the class declaration, the cells in the first column of the table should declare the attributes represented by each row.
• multiple_cells-formatted classes: After the declaration of the table of the parent class, the cells in the second row of the table should declare the attributes represented by each range of columns/rows.

Class instances

Class instances can be encoded into tables as follows:

• row-formatted classes: Each instance is encoded into a row of the table.
• column-formatted classes: Each instance is encoded into a column of the table. This can be used to encode a classes into a transposed table.
• multiple_cells-formatted classes: Each instance is encoded into a range of cells within the row of its parent instance.
• cell-formatted classes: Each instance is encoded into a cell in the row of its parent instance.

Attributes of class instances

The value of each attribute of each instance should be encoded into cells as follows:

• Non-relational attributes: Each value should be serialized into a Boolean, number, or string that can be deserialized by the attribute's deserialize method. For example, dates can be serialized into the format YYYY-MM-DD, and times can be serialized into the format hh:mm:ss. Please see the Python documentation for more information about how each attribute should be serialized.
• Relational (*-to-one) attributes: Each value should be represented by the serialized value of the primary attribute of the related instance. For example, a value of an attribute, which is an instance of a class CreditCard, which has a primary attribute number, should be serialized to the number of the credit card. See above for more information about how to set the primary attribute of a class.
• Relational (*-to-many) attributes: Each value should be represented as a comma-separated list of the serialized value of the primary attributes of the related instances. For example, a value of an attribute which is a list of instances of CreditCard should be serialized to a comma-separated list of the numbers of the credit cards. Primary keys which contain commas or double quotation marks should be enclosed in double quotation marks, similar to CSV files. For example, a list of a, b, "c", d, e should be represented as a, "b, \"c\", d", e. See above for more information about how to set the primary attribute of a class.

Comments about instances of classes

Comments about individual class instances can be encoded as follows:

• row-formatted classes: Comments can be encoded as rows with a single cell in the first column which begins with %/ and ends with /%. Comments should be placed above the instance that the comment applies to.
• column-formatted classes: Comments can similarly be encoded as columns with a single cell that begins with %/ and ends with /%.

Additional tables, rows, and columns not in the schema

Sets of tables that encode datasets can include additional tables, rows, and columns. This can be used to encapsulate additional metadata alongside datasets.

• Additional tables: ObjTables ignores tabular files or worksheets which do not contain class/table declarations. ObjTables also ignores worksheets whose names do not begin with !!.
• Additional columns (row-formatted tables) / rows (column-formatted tables): For row-formatted tables, ObjTables ignores columns whose headings do not begin with !. For column-formatted tables, ObjTables ignores rows whose headings do not begin with !.

JSON/YAML format for datasets

To make it easy to use ObjTables with other programming languages, ObjTables can encode datasets into JSON or YAML documents, which can easily be parsed by a wide range of languages. ObjTables encodes datasets into JSON and YAML as described and illustrated below.

• Classes and metadata: Datasets are encoded into dictionaries. These dictionaries contain the following key-value pairs:
  • Document metadata
    • Key: _documentMetadata.
    • Value: Dictionary of key-value pairs that represent the document-level metadata of the dataset.
  • Class metadata
    • Key: _classMetadata.
    • Value: Dictionary whose keys are the names of the classes in the schema for the dataset and whose values are dictionaries of key-value pairs that represent the metadata for each class.
  • Instances of classes
    • Keys: Names of the classes in the schema.
    • Values: Lists of dictionaries that represent each instance of each class in the dataset.
• Instances of classes: Each object in a dataset is encoded into a dictionary that has the following keys and values:
  • Type
    • Key: __type
    • Value: Name of the class of the object.
  • Unique identifier (used for serializing and deserializing relationships)
    • Key: __id
    • Value: Unique integer-valued id for each object. The ObjTables software automatically generates these ids when it exports a dataset.
  • Attributes
    • Keys: Names of the attributes of the class of the object.
    • Values: Values of the attributes (which are encoded into Booleans, numbers, strings, dictionaries, and lists as appropriate for each type of ObjTables attribute).
• Relationships between instances: Attributes which represent relationships between objects are encoding using the unique integer-value ids generated for each object:
  • Each attribute which represents a *-to-one relationship is encoded into the unique integer id of the related object (or null if there is no related object).
  • Each attribute which represents a *-to-many relationship is encoded into a list of the unique integer ids of the related objects.

{
      # dictionary of metadata about
      # the document
      "_documentMetadata":
      {
    "objTablesVersion": "<ObjTables version>",
    "date": "<Date>",
    ... # additional document metadata
  },

  # dictionary which maps the name of each class
  # to a dictionary with metadata about each class
  "_classMetadata":
  {
    "<ClassName>":
    {
      "id": "<ClassName>",
      "name": "<Class verbose name>",
      ... # additional metadata for the class
    },
    ... # dictionaries with metadata
        # for more classes
  },

  # for each class, lists of dictionaries
  # which represent the instances of the classes
  "<ClassName>":
  [
    {
      "__type": "<ClassName>",
      "__id": <unique integer id>,
      "<attribute name>": <value of attribute>,
      "<*to-one attribute name>":
        <integer id of related object>,
      "<*to-many attribute name>":
        [<integer id of related object>, ...],
      ... # additional attributes of the
          # instance of the class
    },
    ... # additional instances of the class
  ],
  ... # lists of dictionaries which represent the
      # instances of additional classes
}

This Python code illustrates how to decode datasets encoded into this JSON/YAML format. We recommend following this example to create methods for other languages.

ObjTables provides several tools for working with schemas and datasets. The tools marked with ● are available through all of the user interfaces (the web application, web service, command-line program, and Python package). The tools marked with ○ are only available through the Python package. Please see below and the Python documentation for more information about the tools .

• Generate a Python module that implements a tabular-formatted schema.
• Generate a UML diagram for a schema.
• Generate a template CSV, TSV, or XLSX file(s) for a schema.
• Programmatically construct or edit a dataset.
• Merge multiple datasets into a single dataset.
• Partition a dataset into multiple datasets.
• Migrate a dataset between versions of a schema. See the Python documentation for more information.
• Use Git to revision a dataset.
• Validate that a dataset adheres to a schema and report any errors.
• Normalize a dataset into a deterministically reproducible ordering.
• Sort a dataset into a random order.
• Pretty print a dataset.
• Use a schema to determine if two datasets are semantically equivalent.
• Use a schema to evaluate the difference in the semantic meaning of two datasets.
• Parse a dataset into a Python data structure.
• Use a schema to convert a dataset to an alternate format.
• Use a schema to convert a dataset to a dictionary of pandas data frames .

Interfaces

ObjTables include four interfaces: a web application, a web service, a command-line program, and a Python package. The web application, web service, and command-line program provide the same features. In addition to the features of the web application, web service, and command-line program, the Python package can programmatically query, edit, merge, split, revision, and migrate datasets. The Python package is also more flexible. For example, the Python package can support additional datatypes and custom validation.

We recommend beginning with the web application, web service, or command-line program. We recommend using the Python package when more flexibility is required, such as a custom data type, or to analyze datasets with Python tools such as NumPy, Pandas, scikit-learn, or SciPy.

Web application

Command-line program

obj-tables gen-template /path/to/schema.xlsx /path/to/template.xlsx
obj-tables validate /path/to/schema.xlsx /path/to/dataset.xlsx
obj-tables diff /path/to/schema.xlsx /path/to/dataset-1.xlsx /path/to/dataset-2.xlsx

Web service

Python package

apple = Company(
    name='Apple',
    url='https://apple.com/',
    address=Address(
        street='10600 N Tantau Ave',
        city='Cupertino',
        state='CA',
        zip_code='95014',
        country='US'))
facebook = Company(
    name='Facebook',
    url='https://facebook.com/',
    address=Address(
        street='1 Hacker Way #15',
        city='Menlo Park', state='CA',
        zip_code='94025',
        country='US'))
google = Company(
    name='Google',
    url='https://google.com/',
    address=Address(
        street='1600 Amphitheatre Pkwy',
        city='Mountain View',
        state='CA',
        zip_code='94043',
        country='US'))
netflix = Company(
    name='Netflix',
    url='https://netflix.com/',
    address=Address(
        street='100 Winchester Cir',
        city='Los Gatos',
        state='CA',
        zip_code='95032',
        country='US'))
companies = [
    apple,
    facebook,
    google,
    netflix,
]

cook = Person(
    name='Tim Cook',
    type=PersonType.business,
    company=apple,
    email_address='tcook@apple.com',
    phone_number='408-996-1010',
    address=apple.address)
hastings = Person(
    name='Reed Hastings',
    type=PersonType.business,
    company=netflix,
    email_address='reed.hastings@netflix.com',
    phone_number='408-540-3700',
    address=netflix.address)
pichai = Person(
    name='Sundar Pichai',
    type=PersonType.business,
    company=google,
    email_address='sundar@google.com',
    phone_number='650-253-0000',
    address=google.address)
zuckerberg = Person(
    name='Mark Zuckerberg',
    type=PersonType.family,
    company=facebook,
    email_address='zuck@fb.com',
    phone_number='650-543-4800',
    address=facebook.address)

ceos = [
  cook,
  hastings,
  pichai,
  zuckerberg,
]

assert facebook.url == 'https://facebook.com/'

facebook.url = 'https://about.fb.com/'

import obj_tables
errors = obj_tables.Validator().run(
    companies + ceos)
assert errors is None

import obj_tables.io
import os
import tempfile
dirname = tempfile.mkdtemp()
filename_xlsx = os.path.join(
    dirname,
    'address_book.xlsx'
)
obj_tables.io.Writer().run(
    filename_xlsx,
    companies + ceos,
    models=[
        Company,
        Person,
    ]
)

objects = obj_tables.io.Reader().run(
    filename_xlsx,
    models=[
        Company,
        Person,
    ],
    group_objects_by_model=False,
    ignore_sheet_order=True
)

zuckerberg_copy = next(
    el for el in objects 
         if isinstance(el, Person) \
      and el.name == 'Mark Zuckerberg')
assert zuckerberg_copy.is_equal(
    zuckerberg)
assert zuckerberg_copy.difference(
    zuckerberg) == ''