Ignore:
Timestamp:
02/22/13 12:44:33 (14 months ago)
Author:
Ales Erjavec <ales.erjavec@…>
Branch:
default
Message:

Added rst documentation for scheme package.

Fixing docstrings in the process.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • Orange/OrangeCanvas/scheme/scheme.py

    r11275 r11367  
    11""" 
     2=============== 
    23Scheme Workflow 
     4=============== 
     5 
     6The :class:`Scheme` class defines a DAG (Directed Acyclic Graph) workflow. 
    37 
    48""" 
     
    3236 
    3337class Scheme(QObject): 
    34     """An QObject representing the scheme widget workflow 
    35     with annotations, etc. 
    36  
    3738    """ 
    38  
     39    An :class:`QObject` subclass representing the scheme widget workflow 
     40    with annotations. 
     41 
     42    Parameters 
     43    ---------- 
     44    parent : :class:`QObject` 
     45        A parent QObject item (default `None`). 
     46    title : str 
     47        The scheme title. 
     48    description : str 
     49        A longer description of the scheme. 
     50 
     51 
     52    Attributes 
     53    ---------- 
     54    nodes : list of :class:`.SchemeNode` 
     55        A list of all the nodes in the scheme. 
     56 
     57    links : list of :class:`.SchemeLink` 
     58        A list of all links in the scheme. 
     59 
     60    annotations : list of :class:`BaseSchemeAnnotation` 
     61        A list of all the annotations in the scheme. 
     62 
     63    """ 
     64 
     65    # Signal emitted when a `node` is added to the scheme. 
    3966    node_added = Signal(SchemeNode) 
     67 
     68    # Signal emitted when a `node` is removed from the scheme. 
    4069    node_removed = Signal(SchemeNode) 
    4170 
     71    # Signal emitted when a `link` is added to the scheme. 
    4272    link_added = Signal(SchemeLink) 
     73 
     74    # Signal emitted when a `link` is removed from the scheme. 
    4375    link_removed = Signal(SchemeLink) 
    4476 
    45     topology_changed = Signal() 
     77    # Signal emitted when a `annotation` is added to the scheme. 
     78    annotation_added = Signal(BaseSchemeAnnotation) 
     79 
     80    # Signal emitted when a `annotation` is removed from the scheme. 
     81    annotation_removed = Signal(BaseSchemeAnnotation) 
     82 
     83    # Signal emitted when the title of scheme changes. 
     84    title_changed = Signal(unicode) 
     85 
     86    # Signal emitted when the description of scheme changes. 
     87    description_changed = Signal(unicode) 
    4688 
    4789    node_state_changed = Signal() 
    4890    channel_state_changed = Signal() 
    49  
    50     annotation_added = Signal(BaseSchemeAnnotation) 
    51     annotation_removed = Signal(BaseSchemeAnnotation) 
    52  
    53     node_property_changed = Signal(SchemeNode, str, object) 
    54  
    55     title_changed = Signal(unicode) 
    56     description_changed = Signal(unicode) 
     91    topology_changed = Signal() 
    5792 
    5893    def __init__(self, parent=None, title=None, description=None): 
     
    71106    @property 
    72107    def nodes(self): 
     108        """ 
     109        A list of all nodes (:class:`.SchemeNode`) currently in the scheme. 
     110        """ 
    73111        return list(self.__nodes) 
    74112 
    75113    @property 
    76114    def links(self): 
     115        """ 
     116        A list of all links (:class:`.SchemeLink`) currently in the scheme. 
     117        """ 
    77118        return list(self.__links) 
    78119 
    79120    @property 
    80121    def annotations(self): 
     122        """ 
     123        A list of all annotations (:class:`.BaseSchemeAnnotation`) in the 
     124        scheme. 
     125 
     126        """ 
    81127        return list(self.__annotations) 
    82128 
    83129    def set_title(self, title): 
     130        """ 
     131        Set the scheme title text. 
     132        """ 
    84133        if self.__title != title: 
    85134            self.__title = title 
     
    87136 
    88137    def title(self): 
     138        """ 
     139        The title (human readable string) of the scheme. 
     140        """ 
    89141        return self.__title 
    90142 
     
    92144 
    93145    def set_description(self, description): 
     146        """ 
     147        Set the scheme description text. 
     148        """ 
    94149        if self.__description != description: 
    95150            self.__description = description 
     
    97152 
    98153    def description(self): 
     154        """ 
     155        Scheme description text. 
     156        """ 
    99157        return self.__description 
    100158 
     
    102160 
    103161    def add_node(self, node): 
    104         """Add a node to the scheme. 
     162        """ 
     163        Add a node to the scheme. An error is raised if the node is 
     164        already in the scheme. 
    105165 
    106166        Parameters 
    107167        ---------- 
    108         node : `SchemeNode` 
    109             Node to add to the scheme. 
     168        node : :class:`.SchemeNode` 
     169            Node instance to add to the scheme. 
    110170 
    111171        """ 
     
    120180    def new_node(self, description, title=None, position=None, 
    121181                 properties=None): 
    122         """Create a new SchemeNode and add it to the scheme. 
    123         Same as: 
     182        """ 
     183        Create a new :class:`.SchemeNode` and add it to the scheme. 
     184 
     185        Same as:: 
    124186 
    125187            scheme.add_node(SchemeNode(description, title, position, 
    126188                                       properties)) 
     189 
     190        Parameters 
     191        ---------- 
     192        description : :class:`WidgetDescription` 
     193            The new node's description. 
     194        title : str, optional 
     195            Optional new nodes title. By default `description.name` is used. 
     196        position : `(x, y)` tuple of floats, optional 
     197            Optional position in a 2D space. 
     198        properties : dict, optional 
     199            A dictionary of optional extra properties. 
     200 
     201        See also 
     202        -------- 
     203        SchemeNode, Scheme.add_node 
    127204 
    128205        """ 
     
    138215 
    139216    def remove_node(self, node): 
    140         """Remove a `node` from the scheme. All links into and out of the node 
    141         are also removed. 
     217        """ 
     218        Remove a `node` from the scheme. All links into and out of the 
     219        `node` are also removed. If the node in not in the scheme an error 
     220        is raised. 
     221 
     222        Parameters 
     223        ---------- 
     224        node : :class:`.SchemeNode` 
     225            Node instance to remove. 
    142226 
    143227        """ 
     
    152236 
    153237    def __remove_node_links(self, node): 
    154         """Remove all links for node. 
     238        """ 
     239        Remove all links for node. 
    155240        """ 
    156241        links_in, links_out = [], [] 
     
    166251    def add_link(self, link): 
    167252        """ 
    168         Add a link to the scheme. 
     253        Add a `link` to the scheme. 
     254 
     255        Parameters 
     256        ---------- 
     257        link : :class:`.SchemeLink` 
     258            An initialized link instance to add to the scheme. 
     259 
    169260        """ 
    170261        check_type(link, SchemeLink) 
     
    186277        Create a new SchemeLink and add it to the scheme. 
    187278 
    188         Same as: 
     279        Same as:: 
    189280 
    190281            scheme.add_link(SchemeLink(source_node, source_channel, 
    191                                        sink_node, sink_channel) 
     282                                       sink_node, sink_channel)) 
     283 
     284        Parameters 
     285        ---------- 
     286        source_node : :class:`.SchemeNode` 
     287            Source node of the new link. 
     288        source_channel : :class:`OutputSignal` 
     289            Source channel of the new node. The instance must be from 
     290            `source_node.output_channels()` 
     291        sink_node : :class:`.SchemeNode` 
     292            Sink node of the new link. 
     293        sink_channel : :class:`InputSignal` 
     294            Sink channel of the new node. The instance must be from 
     295            `sink_node.input_channels()` 
     296 
     297        See also 
     298        -------- 
     299        SchemeLink, Scheme.add_link 
    192300 
    193301        """ 
     
    198306 
    199307    def remove_link(self, link): 
    200         """Remove a link from the scheme. 
     308        """ 
     309        Remove a link from the scheme. 
     310 
     311        Parameters 
     312        ---------- 
     313        link : :class:`.SchemeLink` 
     314            Link instance to remove. 
     315 
    201316        """ 
    202317        check_arg(link in self.__links, 
     
    213328    def check_connect(self, link): 
    214329        """ 
    215         Check if the link can be added to the scheme. 
     330        Check if the `link` can be added to the scheme. 
    216331 
    217332        Can raise: 
    218             - `TypeError` if link is not an instance of :class:`SchemeLink`. 
    219             - `SchemeCycleError` if the link would introduce a cycle 
    220             - `IncompatibleChannelTypeError` if the channel types are not 
    221                compatible 
    222             - `SinkChannelError` if a sink channel has a `Single` flag 
    223                specification and there is already connected. 
    224             - `DuplicatedLinkError` if a link duplicates an already present 
    225                link. 
     333            - :class:`TypeError` if `link` is not an instance of 
     334              :class:`.SchemeLink` 
     335            - :class:`SchemeCycleError` if the `link` would introduce a cycle 
     336            - :class:`IncompatibleChannelTypeError` if the channel types are 
     337              not compatible 
     338            - :class:`SinkChannelError` if a sink channel has a `Single` flag 
     339              specification and the channel is already connected. 
     340            - :class:`DuplicatedLinkError` if a `link` duplicates an already 
     341              present link. 
    226342 
    227343        """ 
     
    258374 
    259375    def creates_cycle(self, link): 
    260         """Would the `link` if added to the scheme introduce a cycle. 
     376        """ 
     377        Would the `link` if added to the scheme introduce a cycle. 
    261378        """ 
    262379        check_type(link, SchemeLink) 
     
    267384 
    268385    def compatible_channels(self, link): 
    269         """Do the channels in link have compatible types. 
     386        """ 
     387        Do the channels in `link` have compatible types. 
    270388        """ 
    271389        check_type(link, SchemeLink) 
     
    282400 
    283401    def upstream_nodes(self, start_node): 
    284         """Return a set of all nodes upstream from `start_node`. 
     402        """ 
     403        Return a set of all nodes upstream from `start_node`. 
    285404        """ 
    286405        visited = set() 
     
    298417 
    299418    def downstream_nodes(self, start_node): 
    300         """Return a set of all nodes downstream from `start_node`. 
     419        """ 
     420        Return a set of all nodes downstream from `start_node`. 
    301421        """ 
    302422        visited = set() 
     
    314434 
    315435    def is_ancestor(self, node, child): 
    316         """Return True if `node` is an ancestor node of `child` (is upstream 
     436        """ 
     437        Return True if `node` is an ancestor node of `child` (is upstream 
    317438        of the child in the workflow). Both nodes must be in the scheme. 
    318439 
     
    321442 
    322443    def children(self, node): 
    323         """Return a set of all children of `node`. 
     444        """ 
     445        Return a set of all children of `node`. 
    324446        """ 
    325447        return set(link.sink_node for link in self.output_links(node)) 
    326448 
    327449    def parents(self, node): 
    328         """Return a set if all parents of `node`. 
     450        """ 
     451        Return a set of all parents of `node`. 
    329452        """ 
    330453        return set(link.source_node for link in self.input_links(node)) 
    331454 
    332455    def input_links(self, node): 
    333         """Return all input links connected to the `node`. 
     456        """ 
     457        Return all input links connected to the `node` instance. 
    334458        """ 
    335459        return self.find_links(sink_node=node) 
    336460 
    337461    def output_links(self, node): 
    338         """Return all output links connected to the `node`. 
     462        """ 
     463        Return all output links connected to the `node` instance. 
    339464        """ 
    340465        return self.find_links(source_node=node) 
     
    355480 
    356481    def propose_links(self, source_node, sink_node): 
    357         """Return a list of ordered (`OutputSignal`, `InputSignal`, weight) 
    358         tuples that could be added to the scheme between `source_node` and 
    359         `sink_node`. 
     482        """ 
     483        Return a list of ordered (:class:`OutputSignal`, 
     484        :class:`InputSignal`, weight) tuples that could be added to 
     485        the scheme between `source_node` and `sink_node`. 
    360486 
    361487        .. note:: This can depend on the links already in the scheme. 
     
    398524 
    399525    def add_annotation(self, annotation): 
    400         """Add an annotation (`BaseSchemeAnnotation`) subclass to the scheme. 
     526        """ 
     527        Add an annotation (:class:`BaseSchemeAnnotation` subclass) instance 
     528        to the scheme. 
    401529 
    402530        """ 
     
    409537 
    410538    def remove_annotation(self, annotation): 
     539        """ 
     540        Remove the `annotation` instance from the scheme. 
     541        """ 
    411542        check_arg(annotation in self.__annotations, 
    412543                  "Annotation is not in the scheme.") 
     
    415546 
    416547    def save_to(self, stream, pretty=True): 
    417         """Save the scheme as an xml formated file to `stream` 
     548        """ 
     549        Save the scheme as an xml formated file to `stream` 
    418550        """ 
    419551        if isinstance(stream, basestring): 
     
    423555 
    424556    def load_from(self, stream): 
    425         """Load the scheme from xml formated stream. 
     557        """ 
     558        Load the scheme from xml formated stream. 
    426559        """ 
    427560        if self.__nodes or self.__links or self.__annotations: 
Note: See TracChangeset for help on using the changeset viewer.