# class `Model(Properties)`

A Model represents an application data structure which can have observers. The observers are typically subclasses of View, but need not be. Class Model provides mechanisms for attaching and removing observers, and for notifying observers when the Model changes.

A Model can have another Model or Document as a parent. When you call the changed() method of a Model, the call is propagated to its parent, if any. If the Model is ultimately contained in a Document, that Document will then be marked as needing to be saved.

### Pickling behaviour

Models are designed to be pickled as a convenient way of saving and restoring the state of a Document. There are two ways in which class Model provides special support for pickling.

- The link between a Model and its observers is maintained outside the Model object, so that the observers will not be pickled along with the Model.
- There is a mechanism to prevent the parent object of a Model from being pickled when it would not be appropriate to do so. By default, this mechanism is used to prevent a Document reached via the parent attribute of a Model from being pickled. This is important, because normally you only want to save the contents of a Document, not the Document object itself. Furthermore, the Document contains references to the Application and all of the Windows attached to it, so pickling the Document would result in attempting to pickle almost the entire state of the application.
  The mechanism involves looking for an attribute called pickle_as_parent_model on the object referenced by the model's parent attribute. If that attribute exists and has a false value, then the parent attribute is omitted from the pickled state of the Model. Class Document has a pickle_as_parent_model attribute that defaults to False (and you should not change it).
  A consequence is that the parent link from a Model to a containing Document is not automatically restored. You will need to set it yourself after unpickling in the Document's read_contents() method.

## Constructor

Model(parent = None)
  Creates a Model with the specified parent.

## Properties

> `views`
>   List of objects which are observing this Model. Do not modify this list directly; use the `add_view` and `remove_view` methods to add and remove observers.

## Attributes

parent
  Containing Model or Document, if any.

## Methods

> `add_view(view)`
>   Adds the given object as an observer of this Model. If the object defines an `add_model` method, it is called with this Model as argument.
> `remove_view(view)`
>   Removes the given object as an observer of this Model. If the object defines a `remove_model` method, it is called with this Model as argument.
> `notify_views(message = 'model_changed', ...)`
>   Calls a method of each observer with the same name as the message, passing it any additional arguments.
> changed()
>   If the Model is contained in a Document, mark the Document as needing to be saved.

## Pickle protocol

__getstate__()
__setstate__(state)
  These methods implement the special treatment of the parent attribute when pickling. The __getstate__ method returns a possibly-modified version of the Model's __dict__, and the __setstate__ method restores it. If you implement your own custom pickling behaviour, you should build on these methods.

## Destructor

> `destroy`
>   Dissociates the Model from any attached observers, and calls the `model_destroyed` method of each observer which defines it.