@modify_output<EOL>def get_bucket(bucket_name, include_created=None, flags=FLAGS.ALL ^ FLAGS.CREATED_DATE, **conn):

if type(include_created) is bool:<EOL><INDENT>if include_created:<EOL><INDENT>flags = flags | FLAGS.CREATED_DATE<EOL><DEDENT>else:<EOL><INDENT>flags = flags & ~FLAGS.CREATED_DATE<EOL><DEDENT><DEDENT>region = get_bucket_region(Bucket=bucket_name, **conn)<EOL>if not region:<EOL><INDENT>return dict(Error='<STR_LIT>')<EOL><DEDENT>conn['<STR_LIT>'] = region<EOL>return registry.build_out(flags, bucket_name, **conn)<EOL>

Orchestrates all the calls required to fully build out an S3 bucket in the following format:

{
    "Arn": ...,
    "Name": ...,
    "Region": ...,
    "Owner": ...,
    "Grants": ...,
    "GrantReferences": ...,
    "LifecycleRules": ...,
    "Logging": ...,
    "Policy": ...,
    "Tags": ...,
    "Versioning": ...,
    "Website": ...,
    "Cors": ...,
    "Notifications": ...,
    "Acceleration": ...,
    "Replication": ...,
    "CreationDate": ...,
    "AnalyticsConfigurations": ...,
    "MetricsConfigurations": ...,
    "InventoryConfigurations": ...,
    "_version": 9
}

NOTE: "GrantReferences" is an ephemeral field that is not guaranteed to be consistent -- do not base logic off of it

:param include_created: legacy param moved to FLAGS.
:param bucket_name: str bucket name
:param flags: By default, set to ALL fields except for FLAGS.CREATED_DATE as obtaining that information is a slow
              and expensive process.
:param conn: dict containing enough information to make a connection to the desired account. Must at least have
             'assume_role' key.
:return: dict containing a fully built out bucket.


@registry.register(flag=FLAGS.INLINE_POLICIES, key='<STR_LIT>')<EOL>def get_inline_policies(group, **conn):

policy_list = list_group_policies(group['<STR_LIT>'])<EOL>policy_documents = {}<EOL>for policy in policy_list:<EOL><INDENT>policy_documents[policy] = get_group_policy_document(group['<STR_LIT>'], policy, **conn)<EOL><DEDENT>return policy_documents<EOL>


@registry.register(flag=FLAGS.MANAGED_POLICIES, key='<STR_LIT>')<EOL>def get_managed_policies(group, **conn):

managed_policies = list_attached_group_managed_policies(group['<STR_LIT>'], **conn)<EOL>managed_policy_names = []<EOL>for policy in managed_policies:<EOL><INDENT>managed_policy_names.append(policy['<STR_LIT>'])<EOL><DEDENT>return managed_policy_names<EOL>

Get a list of the managed policy names that are attached to the group.


@registry.register(flag=FLAGS.USERS, key='<STR_LIT>')<EOL>def get_users(group, **conn):

group_details = get_group_api(group['<STR_LIT>'], **conn)<EOL>user_list = []<EOL>for user in group_details.get('<STR_LIT>', []):<EOL><INDENT>user_list.append(user['<STR_LIT>'])<EOL><DEDENT>return user_list<EOL>

Gets a list of the usernames that are a part of this group.


group['<STR_LIT>'] = <NUM_LIT:1><EOL>group.update(get_group_api(group['<STR_LIT>'], users=False, **conn)['<STR_LIT>'])<EOL>group['<STR_LIT>'] = get_iso_string(group['<STR_LIT>'])<EOL>return group<EOL>


@modify_output<EOL>def get_group(group, flags=FLAGS.BASE | FLAGS.INLINE_POLICIES | FLAGS.MANAGED_POLICIES, **conn):

if not group.get('<STR_LIT>'):<EOL><INDENT>raise MissingFieldException('<STR_LIT>')<EOL><DEDENT>group = modify(group, output='<STR_LIT>')<EOL>_conn_from_args(group, conn)<EOL>return registry.build_out(flags, start_with=group, pass_datastructure=True, **conn)<EOL>

Orchestrates all the calls required to fully build out an IAM Group in the following format:

{
    "Arn": ...,
    "GroupName": ...,
    "Path": ...,
    "GroupId": ...,
    "CreateDate": ...,  # str
    "InlinePolicies": ...,
    "ManagedPolicies": ...,  # These are just the names of the Managed Policies.
    "Users": ...,  # False by default -- these are just the names of the users.
    "_version": 1
}

:param flags: By default, Users is disabled. This is somewhat expensive as it has to call the `get_group` call
              multiple times.
:param group: dict MUST contain the GroupName and also a combination of either the ARN or the account_number.
:param output: Determines whether keys should be returned camelized or underscored.
:param conn: dict containing enough information to make a connection to the desired account.
             Must at least have 'assume_role' key.
:return: dict containing fully built out Group.


base_fields = frozenset(['<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>'])<EOL>needs_base = False<EOL>for field in base_fields:<EOL><INDENT>if field not in role:<EOL><INDENT>needs_base = True<EOL>break<EOL><DEDENT><DEDENT>if needs_base:<EOL><INDENT>role_name = _get_name_from_structure(role, '<STR_LIT>')<EOL>role = CloudAux.go('<STR_LIT>', RoleName=role_name, **conn)<EOL>role = role['<STR_LIT>']<EOL><DEDENT>role.update(dict(CreateDate=get_iso_string(role['<STR_LIT>'])))<EOL>role['<STR_LIT>'] = <NUM_LIT:3><EOL>return role<EOL>

Determine whether the boto get_role call needs to be made or if we already have all that data
in the role object.
:param role: dict containing (at the very least) role_name and/or arn.
:param conn: dict containing enough information to make a connection to the desired account.
:return: Camelized dict describing role containing all all base_fields.


@modify_output<EOL>def get_role(role, flags=FLAGS.ALL, **conn):

role = modify(role, output='<STR_LIT>')<EOL>_conn_from_args(role, conn)<EOL>return registry.build_out(flags, start_with=role, pass_datastructure=True, **conn)<EOL>

Orchestrates all the calls required to fully build out an IAM Role in the following format:

{
    "Arn": ...,
    "AssumeRolePolicyDocument": ...,
    "CreateDate": ...,  # str
    "InlinePolicies": ...,
    "InstanceProfiles": ...,
    "ManagedPolicies": ...,
    "Path": ...,
    "RoleId": ...,
    "RoleName": ...,
    "Tags": {},
    "_version": 3
}

:param role: dict containing (at the very least) role_name and/or arn.
:param output: Determines whether keys should be returned camelized or underscored.
:param conn: dict containing enough information to make a connection to the desired account.
Must at least have 'assume_role' key.
:return: dict containing a fully built out role.


roles = []<EOL>account_roles = get_account_authorization_details('<STR_LIT>', **conn)<EOL>for role in account_roles:<EOL><INDENT>roles.append(<EOL>{<EOL>'<STR_LIT>': role['<STR_LIT>'],<EOL>'<STR_LIT>': role['<STR_LIT>'],<EOL>'<STR_LIT>': get_iso_string(role['<STR_LIT>']),<EOL>'<STR_LIT>': role['<STR_LIT>'],<EOL>'<STR_LIT>': [{<EOL>'<STR_LIT:path>': ip['<STR_LIT>'],<EOL>'<STR_LIT>': ip['<STR_LIT>'],<EOL>'<STR_LIT>': get_iso_string(ip['<STR_LIT>']),<EOL>'<STR_LIT>': ip['<STR_LIT>'],<EOL>'<STR_LIT>': ip['<STR_LIT>']<EOL>} for ip in role['<STR_LIT>']],<EOL>'<STR_LIT>': [<EOL>{<EOL>"<STR_LIT:name>": x['<STR_LIT>'],<EOL>"<STR_LIT>": x['<STR_LIT>']<EOL>} for x in role['<STR_LIT>']<EOL>],<EOL>'<STR_LIT>': role['<STR_LIT>'],<EOL>'<STR_LIT>': role['<STR_LIT>'],<EOL>'<STR_LIT>': role['<STR_LIT>']<EOL>}<EOL>)<EOL><DEDENT>return roles<EOL>

Returns a List of Roles represented as the dictionary below:

{
    "Arn": ...,
    "AssumeRolePolicyDocument": ...,
    "CreateDate": ...,  # str
    "InlinePolicies": ...,
    "InstanceProfiles": ...,
    "ManagedPolicies": ...,
    "Path": ...,
    "RoleId": ...,
    "RoleName": ...,
}

:param conn: dict containing enough information to make a connection to the desired account.
:return: list containing dicts or fully built out roles


@modify_output<EOL>def get_user(user, flags=FLAGS.ALL, **conn):

user = modify(user, output='<STR_LIT>')<EOL>_conn_from_args(user, conn)<EOL>return registry.build_out(flags, start_with=user, pass_datastructure=True, **conn)<EOL>

Orchestrates all the calls required to fully build out an IAM User in the following format:

{
    "Arn": ...,
    "AccessKeys": ...,
    "CreateDate": ...,  # str
    "InlinePolicies": ...,
    "ManagedPolicies": ...,
    "MFADevices": ...,
    "Path": ...,
    "UserId": ...,
    "UserName": ...,
    "SigningCerts": ...
}

:param user: dict MUST contain the UserName and also a combination of either the ARN or the account_number
:param output: Determines whether keys should be returned camelized or underscored.
:param conn: dict containing enough information to make a connection to the desired account.
Must at least have 'assume_role' key.
:return: dict containing fully built out user.


def get_all_users(flags=FLAGS.ACCESS_KEYS | FLAGS.MFA_DEVICES | FLAGS.LOGIN_PROFILE | FLAGS.SIGNING_CERTIFICATES,<EOL>**conn):

users = []<EOL>account_users = get_account_authorization_details('<STR_LIT>', **conn)<EOL>for user in account_users:<EOL><INDENT>temp_user = {<EOL>'<STR_LIT>': user['<STR_LIT>'],<EOL>'<STR_LIT>': get_iso_string(user['<STR_LIT>']),<EOL>'<STR_LIT>': user['<STR_LIT>'],<EOL>'<STR_LIT>': user['<STR_LIT>'],<EOL>'<STR_LIT>': [<EOL>{<EOL>"<STR_LIT:name>": x['<STR_LIT>'],<EOL>"<STR_LIT>": x['<STR_LIT>']<EOL>} for x in user['<STR_LIT>']<EOL>],<EOL>'<STR_LIT>': user['<STR_LIT>'],<EOL>'<STR_LIT>': user['<STR_LIT>'],<EOL>'<STR_LIT>': user['<STR_LIT>']<EOL>}<EOL>user = modify(temp_user, output='<STR_LIT>')<EOL>_conn_from_args(user, conn)<EOL>users.append(registry.build_out(flags, start_with=user, pass_datastructure=True, **conn))<EOL><DEDENT>return users<EOL>

Returns a list of Users represented as dictionary below:

{
    "Arn": ...,
    "AccessKeys": ...,
    "CreateDate": ...,  # str
    "InlinePolicies": ...,
    "ManagedPolicies": ...,
    "MFADevices": ...,
    "Path": ...,
    "UserId": ...,
    "UserName": ...,
    "SigningCerts": ...
}

:param flags:
:param conn: dict containing enough information to make a connection to the desired account.
:return: list of dicts containing fully built out user.


managed_policy['<STR_LIT>'] = <NUM_LIT:1><EOL>arn = _get_name_from_structure(managed_policy, '<STR_LIT>')<EOL>policy = get_policy(arn, **conn)<EOL>document = get_managed_policy_document(arn, policy_metadata=policy, **conn)<EOL>managed_policy.update(policy['<STR_LIT>'])<EOL>managed_policy['<STR_LIT>'] = document<EOL>managed_policy['<STR_LIT>'] = get_iso_string(managed_policy['<STR_LIT>'])<EOL>managed_policy['<STR_LIT>'] = get_iso_string(managed_policy['<STR_LIT>'])<EOL>return managed_policy<EOL>

Fetch the base Managed Policy.

    This includes the base policy and the latest version document.

    :param managed_policy:
    :param conn:
    :return:


@modify_output<EOL>def get_managed_policy(managed_policy, flags=FLAGS.ALL, **conn):

_conn_from_args(managed_policy, conn)<EOL>return registry.build_out(flags, start_with=managed_policy, pass_datastructure=True, **conn)<EOL>

Orchestrates all of the calls required to fully build out an IAM Managed Policy in the following format:

{
    "Arn": "...",
    "PolicyName": "...",
    "PolicyId": "...",
    "Path": "...",
    "DefaultVersionId": "...",
    "AttachmentCount": 123,
    "PermissionsBoundaryUsageCount": 123,
    "IsAttachable": ...,
    "Description": "...",
    "CreateDate": "...",
    "UpdateDate": "...",
    "Document": "...",
    "_version": 1
}

:param managed_policy: dict MUST contain the ARN.
:param flags:
:param conn:
:return:


server_certificate['<STR_LIT>'] = <NUM_LIT:1><EOL>cert_details = get_server_certificate_api(server_certificate['<STR_LIT>'], **conn)<EOL>if cert_details:<EOL><INDENT>server_certificate.update(cert_details['<STR_LIT>'])<EOL>server_certificate['<STR_LIT>'] = cert_details['<STR_LIT>']<EOL>server_certificate['<STR_LIT>'] = cert_details.get('<STR_LIT>', None)<EOL>server_certificate['<STR_LIT>'] = get_iso_string(server_certificate['<STR_LIT>'])<EOL>server_certificate['<STR_LIT>'] = get_iso_string(server_certificate['<STR_LIT>'])<EOL><DEDENT>return server_certificate<EOL>


@modify_output<EOL>def get_server_certificate(server_certificate, flags=FLAGS.BASE, **conn):

if not server_certificate.get('<STR_LIT>'):<EOL><INDENT>raise MissingFieldException('<STR_LIT>')<EOL><DEDENT>server_certificate = modify(server_certificate, output='<STR_LIT>')<EOL>_conn_from_args(server_certificate, conn)<EOL>return registry.build_out(flags, start_with=server_certificate, pass_datastructure=True, **conn)<EOL>

Orchestrates all the calls required to fully build out an IAM User in the following format:

{
    "Arn": ...,
    "ServerCertificateName": ...,
    "Path": ...,
    "ServerCertificateId": ...,
    "UploadDate": ...,  # str
    "Expiration": ...,  # str
    "CertificateBody": ...,
    "CertificateChain": ...,
    "_version": 1
}

:param flags: By default, Users is disabled. This is somewhat expensive as it has to call the
              `get_server_certificate` call multiple times.
:param server_certificate: dict MUST contain the ServerCertificateName and also a combination of
                           either the ARN or the account_number.
:param output: Determines whether keys should be returned camelized or underscored.
:param conn: dict containing enough information to make a connection to the desired account.
             Must at least have 'assume_role' key.
:return: dict containing fully built out Server Certificate.


@modify_output<EOL>def get_event(rule, flags=FLAGS.ALL, **conn):

<EOL>try:<EOL><INDENT>basestring<EOL><DEDENT>except NameError as _:<EOL><INDENT>basestring = str<EOL><DEDENT>if isinstance(rule, basestring):<EOL><INDENT>rule_arn = ARN(rule)<EOL>if rule_arn.error:<EOL><INDENT>rule_name = rule<EOL><DEDENT>else:<EOL><INDENT>rule_name = rule_arn.name<EOL><DEDENT><DEDENT>rule = describe_rule(Name=rule_name, **conn)<EOL>return registry.build_out(flags, rule, **conn)<EOL>

Orchestrates all the calls required to fully build out a CloudWatch Event Rule in the following format:

{
    "Arn": ...,
    "Name": ...,
    "Region": ...,
    "Description": ...,
    "State": ...,
    "Rule": ...,
    "Targets" ...,
    "_version": 1
}

:param rule: str cloudwatch event name
:param flags: By default, set to ALL fields
:param conn: dict containing enough information to make a connection to the desired account.
Must at least have 'assume_role' key.
:return: dict containing a fully built out event rule with targets.


rules = security_group.pop('<STR_LIT>',[])<EOL>for rule in rules:<EOL><INDENT>rule['<STR_LIT>'] = rule.pop('<STR_LIT>')<EOL>rule['<STR_LIT>'] = rule.pop('<STR_LIT>')<EOL>rule['<STR_LIT>'] = rule.pop('<STR_LIT>')<EOL>rule['<STR_LIT>'] = rule.pop('<STR_LIT>')<EOL>rule['<STR_LIT>'] = rule.pop('<STR_LIT>')<EOL><DEDENT>security_group['<STR_LIT>'] = sorted(rules)<EOL>return security_group<EOL>

format the rule fields to match AWS to support auditor reuse,
        will need to remap back if we want to orchestrate from our stored items


_item = {}<EOL>for k,v in inspect.getmembers(item, lambda a:not(inspect.isroutine(a))):<EOL><INDENT>if not k.startswith('<STR_LIT:_>') and not k in ignore_list:<EOL><INDENT>_item[k] = v<EOL><DEDENT><DEDENT>return sub_dict(_item)<EOL>

API versioning for each OpenStack service is independent. Generically capture
    the public members (non-routine and non-private) of the OpenStack SDK objects.

Note the lack of the modify_output decorator. Preserving the field naming allows
    us to reconstruct objects and orchestrate from stored items.


r = []<EOL>for i in l:<EOL><INDENT>if type(i) in prims:<EOL><INDENT>r.append(i)<EOL><DEDENT>elif type(i) is list:<EOL><INDENT>r.append(sub_list(i))<EOL><DEDENT>elif type(i) is dict:<EOL><INDENT>r.append(sub_dict(i))<EOL><DEDENT>else:<EOL><INDENT>r.append(str(i))<EOL><DEDENT><DEDENT>r = sorted(r)<EOL>return r<EOL>

Recursively walk a data-structure sorting any lists along the way.
Any unknown types get mapped to string representation

:param l: list
:return: sorted list, where any child lists are also sorted.


r = {}<EOL>for k in d:<EOL><INDENT>if type(d[k]) in prims:<EOL><INDENT>r[k] = d[k]<EOL><DEDENT>elif type(d[k]) is list:<EOL><INDENT>r[k] = sub_list(d[k])<EOL><DEDENT>elif type(d[k]) is dict:<EOL><INDENT>r[k] = sub_dict(d[k])<EOL><DEDENT>else:<EOL><INDENT>r[k] = str(d[k])<EOL><DEDENT><DEDENT>return r<EOL>

Recursively walk a data-structure sorting any lists along the way.
Any unknown types get mapped to string representation

:param d: dict
:return: dict where any lists, even those buried deep in the structure, have been sorted.


result = dict()<EOL>for key in item:<EOL><INDENT>result[func(key)] = item[key]<EOL><DEDENT>return result<EOL>

Modifies each item.keys() string based on the func passed in.
Often used with inflection's camelize or underscore methods.

:param item: dictionary representing item to be modified
:param func: function to run on each key string
:return: dictionary where each key has been modified by func.


if output == '<STR_LIT>':<EOL><INDENT>return _modify(item, camelize)<EOL><DEDENT>elif output == '<STR_LIT>':<EOL><INDENT>return _modify(item, underscore)<EOL><DEDENT>

Calls _modify and either passes the inflection.camelize method or the inflection.underscore method.

:param item: dictionary representing item to be modified
:param output: string 'camelized' or 'underscored'
:return:


return input.replace(tzinfo=None, microsecond=<NUM_LIT:0>).isoformat() + '<STR_LIT>'<EOL>

Strips out the microseconds from datetime objects, and returns a proper ISO-format UTC string.

    :param input: Datetime object.
    :returns string: A datetime ISO format string with


cloudaux = CloudAux(
    **{'account_number': '000000000000',
       'assume_role': 'role_name',
    })


def call(self, function_expr, **kwargs):

if '<STR_LIT:.>' in function_expr:<EOL><INDENT>tech, service_type, function_name = function_expr.split('<STR_LIT:.>')<EOL><DEDENT>else:<EOL><INDENT>tech = self.conn_details.get('<STR_LIT>')<EOL>service_type = self.conn_details.get('<STR_LIT>', '<STR_LIT>')<EOL>function_name = function_expr<EOL><DEDENT>@sts_conn(tech, service_type=service_type)<EOL>def wrapped_method(function_name, **nargs):<EOL><INDENT>service_type = nargs.pop(nargs.pop('<STR_LIT>', '<STR_LIT>'))<EOL>return getattr(service_type, function_name)(**nargs)<EOL><DEDENT>kwargs.update(self.conn_details)<EOL>if '<STR_LIT>' in kwargs:<EOL><INDENT>del kwargs['<STR_LIT>']<EOL><DEDENT>return wrapped_method(function_name, **kwargs)<EOL>

cloudaux = CloudAux(
    **{'account_number': '000000000000',
       'assume_role': 'role_name',
       'session_name': 'testing',
       'region': 'us-east-1',
       'tech': 'kms',
       'service_type': 'client'
    })

cloudaux.call("list_aliases")
cloudaux.call("kms.client.list_aliases")


if '<STR_LIT:.>' in function_expr:<EOL><INDENT>tech, service_type, function_name = function_expr.split('<STR_LIT:.>')<EOL><DEDENT>else:<EOL><INDENT>tech = kwargs.pop('<STR_LIT>')<EOL>service_type = kwargs.get('<STR_LIT>')<EOL>function_name = function_expr<EOL><DEDENT>@sts_conn(tech, service_type=service_type)<EOL>def wrapped_method(function_name, **nargs):<EOL><INDENT>service_type = nargs.pop(nargs.pop('<STR_LIT>', '<STR_LIT>'))<EOL>return getattr(service_type, function_name)(**nargs)<EOL><DEDENT>return wrapped_method(function_name, **kwargs)<EOL>

CloudAux.go(
    'list_aliases',
    **{
        'account_number': '000000000000',
        'assume_role': 'role_name',
        'session_name': 'cloudaux',
        'region': 'us-east-1',
        'tech': 'kms',
        'service_type': 'client'
    })

CloudAux.go(
    'kms.client.list_aliases',
    **{
        'account_number': '000000000000',
        'assume_role': 'role_name',
        'session_name': 'cloudaux',
        'region': 'us-east-1'
    })


def get(self, key, delete_if_expired=True):

self._update_cache_stats(key, None)<EOL>if key in self._CACHE:<EOL><INDENT>(expiration, obj) = self._CACHE[key]<EOL>if expiration > self._now():<EOL><INDENT>self._update_cache_stats(key, '<STR_LIT>')<EOL>return obj<EOL><DEDENT>else:<EOL><INDENT>if delete_if_expired:<EOL><INDENT>self.delete(key)<EOL>self._update_cache_stats(key, '<STR_LIT>')<EOL>return None<EOL><DEDENT><DEDENT><DEDENT>self._update_cache_stats(key, '<STR_LIT>')<EOL>return None<EOL>

Retrieve key from Cache.

:param key: key to look up in cache.
:type key: ``object``

:param delete_if_expired: remove value from cache if it is expired.
                          Default is True.
:type delete_if_expired: ``bool``

:returns: value from cache or None
:rtype: varies or None


def insert(self, key, obj, future_expiration_minutes=<NUM_LIT:15>):

expiration_time = self._calculate_expiration(future_expiration_minutes)<EOL>self._CACHE[key] = (expiration_time, obj)<EOL>return True<EOL>

Insert item into cache.

:param key: key to look up in cache.
:type key: ``object``

:param obj: item to store in cache.
:type obj: varies

:param future_expiration_minutes: number of minutes item is valid
:type param: ``int``

:returns: True
:rtype: ``bool``


def _update_cache_stats(self, key, result):

if result is None:<EOL><INDENT>self._CACHE_STATS['<STR_LIT>'].setdefault(key,<EOL>{'<STR_LIT>': <NUM_LIT:0>, '<STR_LIT>': <NUM_LIT:0>, '<STR_LIT>': <NUM_LIT:0>})<EOL><DEDENT>else:<EOL><INDENT>self._CACHE_STATS['<STR_LIT>'][key][result] +=<NUM_LIT:1><EOL><DEDENT>

Update the cache stats.

If no cache-result is specified, we iniitialize the key.
Otherwise, we increment the correct cache-result.

Note the behavior for expired.  A client can be expired and the key
still exists.


if key in self._CACHE_STATS:<EOL><INDENT>return self._CACHE_STATS['<STR_LIT>'][key]<EOL><DEDENT>else:<EOL><INDENT>return self._CACHE_STATS['<STR_LIT>']<EOL><DEDENT>


expired = sum([x['<STR_LIT>'] for _, x in<EOL>self._CACHE_STATS['<STR_LIT>'].items()])<EOL>miss = sum([x['<STR_LIT>'] for _, x in<EOL>self._CACHE_STATS['<STR_LIT>'].items()])<EOL>hit = sum([x['<STR_LIT>'] for _, x in<EOL>self._CACHE_STATS['<STR_LIT>'].items()])<EOL>return {<EOL>'<STR_LIT>': {<EOL>'<STR_LIT>': len(self._CACHE_STATS['<STR_LIT>']),<EOL>'<STR_LIT>': expired,<EOL>'<STR_LIT>': miss,<EOL>'<STR_LIT>': hit,<EOL>}<EOL>}<EOL>


client_details = choose_client(service)<EOL>user_agent = get_user_agent(**conn_args)<EOL>if client_details:<EOL><INDENT>if client_details['<STR_LIT>'] == '<STR_LIT>':<EOL><INDENT>client = get_gcp_client(<EOL>mod_name=client_details['<STR_LIT>'],<EOL>pkg_name=conn_args.get('<STR_LIT>', '<STR_LIT>'),<EOL>key_file=conn_args.get('<STR_LIT>', None),<EOL>project=conn_args['<STR_LIT>'], user_agent=user_agent)<EOL><DEDENT>else:<EOL><INDENT>client = get_google_client(<EOL>mod_name=client_details['<STR_LIT>'],<EOL>key_file=conn_args.get('<STR_LIT>', None),<EOL>user_agent=user_agent, api_version=conn_args.get('<STR_LIT>', '<STR_LIT>'))<EOL><DEDENT><DEDENT>else:<EOL><INDENT>try:<EOL><INDENT>client = get_google_client(<EOL>mod_name=service, key_file=conn_args.get('<STR_LIT>', None),<EOL>user_agent=user_agent, api_version=conn_args.get('<STR_LIT>', '<STR_LIT>'))<EOL><DEDENT>except Exception as e:<EOL><INDENT>raise e<EOL><DEDENT><DEDENT>return client_details, client<EOL>

User function to get the correct client.

Based on the GOOGLE_CLIENT_MAP dictionary, the return will be a cloud or general
client that can interact with the desired service.

:param service: GCP service to connect to. E.g. 'gce', 'iam'
:type service: ``str``

:param conn_args: Dictionary of connection arguments.  'project' is required.
                  'user_agent' can be specified and will be set in the client
                   returned.
:type conn_args: ``dict``

:return: client_details, client
:rtype: ``tuple`` of ``dict``, ``object``


client_options = get_available_clients(service)<EOL>if client_options:<EOL><INDENT>return client_options[<NUM_LIT:0>]<EOL><DEDENT>return None<EOL>

Logic to choose the appropriate client.

:param service: Google Cloud service name. Examples: 'iam', 'gce'.
:type service: ``str``

:return: specific dictionary recommended for a particular service.
:rtype: ``dict``


details = GOOGLE_CLIENT_MAP.get(service, None)<EOL>if details:<EOL><INDENT>return [details]<EOL><DEDENT>else:<EOL><INDENT>return None<EOL><DEDENT>

Return clients available for this service.

:param service: Google Cloud service name. Examples: 'iam', 'gce'.
:type service: ``str``

:return: list of dictionaries describing the clients available.
:rtype: ``list``


return _gcp_client(project=kwargs['<STR_LIT>'], mod_name=kwargs['<STR_LIT>'],<EOL>pkg_name=kwargs.get('<STR_LIT>', '<STR_LIT>'),<EOL>key_file=kwargs.get('<STR_LIT>', None),<EOL>http_auth=kwargs.get('<STR_LIT:http>', None),<EOL>user_agent=kwargs.get('<STR_LIT>', None))<EOL>


def _gcp_client(project, mod_name, pkg_name, key_file=None, http_auth=None,<EOL>user_agent=None):

client = None<EOL>if http_auth is None:<EOL><INDENT>http_auth = _googleauth(key_file=key_file, user_agent=user_agent)<EOL><DEDENT>try:<EOL><INDENT>google_module = importlib.import_module('<STR_LIT:.>' + mod_name,<EOL>package=pkg_name)<EOL>client = google_module.Client(use_GAX=USE_GAX, project=project,<EOL>http=http_auth)<EOL><DEDENT>except ImportError as ie:<EOL><INDENT>import_err = '<STR_LIT>' % (pkg_name, mod_name)<EOL>raise ImportError(import_err)<EOL><DEDENT>except TypeError:<EOL><INDENT>client = google_module.Client(project=project, http=http_auth)<EOL><DEDENT>if user_agent and hasattr(client, '<STR_LIT>'):<EOL><INDENT>client.user_agent = user_agent<EOL><DEDENT>return client<EOL>

Private GCP client builder.

:param project: Google Cloud project string.
:type project: ``str``

:param mod_name: Module name to load.  Should be found in sys.path.
:type mod_name: ``str``

:param pkg_name: package name that mod_name is part of.  Default is 'google.cloud' .
:type pkg_name: ``str``

:param key_file: Default is None.
:type key_file: ``str`` or None

:param http_auth: httplib2 authorized client. Default is None.
:type http_auth: :class: `HTTPLib2`

:param user_agent: User Agent string to use in requests. Default is None.
:type http_auth: ``str`` or None

:return: GCP client
:rtype: ``object``


def _googleauth(key_file=None, scopes=[], user_agent=None):

if key_file:<EOL><INDENT>if not scopes:<EOL><INDENT>scopes = DEFAULT_SCOPES<EOL><DEDENT>creds = ServiceAccountCredentials.from_json_keyfile_name(key_file,<EOL>scopes=scopes)<EOL><DEDENT>else:<EOL><INDENT>creds = GoogleCredentials.get_application_default()<EOL><DEDENT>http = Http()<EOL>if user_agent:<EOL><INDENT>http = set_user_agent(http, user_agent)<EOL><DEDENT>http_auth = creds.authorize(http)<EOL>return http_auth<EOL>

Google http_auth helper.

If key_file is not specified, default credentials will be used.

If scopes is specified (and key_file), will be used instead of DEFAULT_SCOPES

:param key_file: path to key file to use. Default is None
:type key_file: ``str``

:param scopes: scopes to set.  Default is DEFAUL_SCOPES
:type scopes: ``list``

:param user_agent: User Agent string to use in requests. Default is None.
:type http_auth: ``str`` or None

:return: HTTPLib2 authorized client.
:rtype: :class: `HTTPLib2`


def _build_google_client(service, api_version, http_auth):

client = build(service, api_version, http=http_auth)<EOL>return client<EOL>

Google build client helper.

:param service: service to build client for
:type service: ``str``

:param api_version: API version to use.
:type api_version: ``str``

:param http_auth: Initialized HTTP client to use.
:type http_auth: ``object``

:return: google-python-api client initialized to use 'service'
:rtype: ``object``


return gce_list(service=client.firewalls(),<EOL>**kwargs)<EOL>


return gce_list(service=client.networks(),<EOL>**kwargs)<EOL>


return gce_list_aggregated(service=client.subnetworks(),<EOL>key_name='<STR_LIT>', **kwargs)<EOL>


buckets = client.list_buckets(**kwargs)<EOL>return [b.__dict__ for b in buckets]<EOL>

List buckets for a project.

:param client: client object to use.
:type client: Google Cloud Storage client

:returns: list of dictionary reprsentation of Bucket
:rtype: ``list`` of ``dict``


bucket = client.lookup_bucket(kwargs['<STR_LIT>'])<EOL>return bucket<EOL>

Get bucket object.

:param client: client object to use.
:type client: Google Cloud Storage client

:returns: Bucket object
:rtype: ``object``


bucket = get_bucket(**kwargs)<EOL>if bucket:<EOL><INDENT>return getattr(bucket, kwargs['<STR_LIT>'], None)<EOL><DEDENT>else:<EOL><INDENT>return None<EOL><DEDENT>

Get value from member field of bucket object.

:param Field: name of member of Bucket object to return.
:type Field: ``str``

:returns: value contained by the specified member field.
:rtype: varies


bucket = get_bucket(**kwargs)<EOL>if bucket:<EOL><INDENT>return [o for o in bucket.list_blobs()]<EOL><DEDENT>else:<EOL><INDENT>return None<EOL><DEDENT>

List objects in bucket.

:param Bucket: name of bucket
:type Bucket: ``str``

:returns list of objects in bucket
:rtype: ``list``


bucket = get_bucket(**kwargs)<EOL>if bucket:<EOL><INDENT>return bucket.get_blob(kwargs['<STR_LIT>'])<EOL><DEDENT>else:<EOL><INDENT>return None<EOL><DEDENT>

Retrieve object from Bucket.

:param Bucket: name of bucket
:type Bucket: ``str``

:returns: object from bucket or None
:rtype ``object`` or None


creds = {<EOL>'<STR_LIT>': kwargs.pop('<STR_LIT>', None),<EOL>'<STR_LIT>': kwargs.pop('<STR_LIT>', None),<EOL>'<STR_LIT>': kwargs.get('<STR_LIT>', None),<EOL>'<STR_LIT>': kwargs.pop('<STR_LIT>', None),<EOL>'<STR_LIT>': kwargs.pop('<STR_LIT>', '<STR_LIT>')<EOL>}<EOL>return (creds, kwargs)<EOL>


def rewrite_kwargs(conn_type, kwargs, module_name=None):

if conn_type != '<STR_LIT>' and module_name != '<STR_LIT>':<EOL><INDENT>if '<STR_LIT>' in kwargs:<EOL><INDENT>kwargs['<STR_LIT:name>'] = '<STR_LIT>' % kwargs.pop('<STR_LIT>')<EOL><DEDENT><DEDENT>if conn_type == '<STR_LIT>' and module_name == '<STR_LIT>':<EOL><INDENT>if '<STR_LIT>' in kwargs:<EOL><INDENT>del kwargs['<STR_LIT>']<EOL><DEDENT><DEDENT>return kwargs<EOL>

Manipulate connection keywords.

Modifieds keywords based on connection type.

There is an assumption here that the client has
already been created and that these keywords are being
passed into methods for interacting with various services.

Current modifications:
- if conn_type is not cloud and module is 'compute',
  then rewrite project as name.
- if conn_type is cloud and module is 'storage',
  then remove 'project' from dict.

:param conn_type: E.g. 'cloud' or 'general'
:type conn_type: ``str``

:param kwargs: Dictionary of keywords sent in by user.
:type kwargs: ``dict``

:param module_name: Name of specific module that will be loaded.
                    Default is None.
:type conn_type: ``str`` or None

:returns kwargs with client and module specific changes
:rtype: ``dict``


def gce_list_aggregated(service=None, key_name='<STR_LIT:name>', **kwargs):

resp_list = []<EOL>req = service.aggregatedList(**kwargs)<EOL>while req is not None:<EOL><INDENT>resp = req.execute()<EOL>for location, item in resp['<STR_LIT>'].items():<EOL><INDENT>if key_name in item:<EOL><INDENT>resp_list.extend(item[key_name])<EOL><DEDENT><DEDENT>req = service.aggregatedList_next(previous_request=req,<EOL>previous_response=resp)<EOL><DEDENT>return resp_list<EOL>

General aggregated list function for the GCE service.


resp_list = []<EOL>req = service.list(**kwargs)<EOL>while req is not None:<EOL><INDENT>resp = req.execute()<EOL>for item in resp.get('<STR_LIT>', []):<EOL><INDENT>resp_list.append(item)<EOL><DEDENT>req = service.list_next(previous_request=req, previous_response=resp)<EOL><DEDENT>return resp_list<EOL>

General list function for the GCE service.


def service_list(service=None, key_name=None, **kwargs):

resp_list = []<EOL>req = service.list(**kwargs)<EOL>while req is not None:<EOL><INDENT>resp = req.execute()<EOL>if key_name and key_name in resp:<EOL><INDENT>resp_list.extend(resp[key_name])<EOL><DEDENT>else:<EOL><INDENT>resp_list.append(resp)<EOL><DEDENT>if hasattr(service, '<STR_LIT>'):<EOL><INDENT>req = service.list_next(previous_request=req,<EOL>previous_response=resp)<EOL><DEDENT>else:<EOL><INDENT>req = None<EOL><DEDENT><DEDENT>return resp_list<EOL>


from cloudaux.gcp.decorators import _GCP_CACHE<EOL>return _GCP_CACHE.get_stats()<EOL>


from cloudaux.gcp.decorators import _GCP_CACHE<EOL>return _GCP_CACHE.get_access_details(key=key)<EOL>


from cloudaux.gcp.decorators import _GCP_STATS<EOL>return _GCP_STATS<EOL>

Retrieve stats, such as function timings.


version = '<STR_LIT>'<EOL>try:<EOL><INDENT>import pkg_resources<EOL>version = pkg_resources.get_distribution(pkg_name).version<EOL><DEDENT>except pkg_resources.DistributionNotFound:<EOL><INDENT>pass<EOL><DEDENT>except ImportError:<EOL><INDENT>pass<EOL><DEDENT>return '<STR_LIT>' % (version)<EOL>

Get default User Agent String.

Try to import pkg_name to get an accurate version number.

return: string


user_agent = kwargs.get('<STR_LIT>', None)<EOL>if not user_agent:<EOL><INDENT>return get_user_agent_default()<EOL><DEDENT>return user_agent<EOL>

If there is a useragent, find it.

Look in the keywords for user_agent. If not found,
return get_user_agent_default


def _build_key(func_name, args, kwargs):

return "<STR_LIT>" % (func_name, args, kwargs)<EOL>


def gcp_conn(service, service_type='<STR_LIT>', future_expiration_minutes=<NUM_LIT:15>):

def decorator(f):<EOL><INDENT>@wraps(f)<EOL>def decorated_function(*args, **kwargs):<EOL><INDENT>from cloudaux.gcp.auth import get_client<EOL>(conn_args, kwargs) = get_creds_from_kwargs(kwargs)<EOL>client_details, client = get_client(<EOL>service, service_type=service_type,<EOL>future_expiration_minutes=<NUM_LIT:15>, **conn_args)<EOL>if client_details:<EOL><INDENT>kwargs = rewrite_kwargs(client_details['<STR_LIT>'], kwargs,<EOL>client_details['<STR_LIT>'])<EOL><DEDENT>kwargs['<STR_LIT>'] = client<EOL>return f(*args, **kwargs)<EOL><DEDENT>return decorated_function<EOL><DEDENT>return decorator<EOL>


def decorator(f):<EOL><INDENT>@wraps(f)<EOL>def decorated_function(*args, **kwargs):<EOL><INDENT>start_time = time.time()<EOL>result = f(*args, **kwargs)<EOL>end_time = time.time()<EOL>strkey = _build_key(f.__name__, args, kwargs)<EOL>_GCP_STATS.setdefault(strkey, []).append(end_time - start_time)<EOL>return result<EOL><DEDENT>return decorated_function<EOL><DEDENT>return decorator<EOL>

Collect stats

Specifically, time function calls
:returns: function response
:rtype: varies


def decorator(f):<EOL><INDENT>@wraps(f)<EOL>def decorated_function(*args, **kwargs):<EOL><INDENT>strkey = _build_key(f.__name__, args, kwargs)<EOL>cached_result = _GCP_CACHE.get(strkey)<EOL>if cached_result:<EOL><INDENT>return cached_result<EOL><DEDENT>else:<EOL><INDENT>result = f(*args, **kwargs)<EOL>_GCP_CACHE.insert(strkey, result, future_expiration_minutes)<EOL><DEDENT>return result<EOL><DEDENT>return decorated_function<EOL><DEDENT>return decorator<EOL>

Cache function output
:param future_expiration_minutes: Number of minutes in the future until item
                                  expires.  Default is 15.
:returns: function response, optionally from the cache
:rtype: varies


def decorator(func):<EOL><INDENT>@wraps(func)<EOL>def decorated_function(*args, **kwargs):<EOL><INDENT>item_list = []<EOL>exception_map = {}<EOL>for project in projects:<EOL><INDENT>if isinstance(project, string_types):<EOL><INDENT>kwargs['<STR_LIT>'] = project<EOL>if key_file:<EOL><INDENT>kwargs['<STR_LIT>'] = key_file<EOL><DEDENT><DEDENT>elif isinstance(project, dict):<EOL><INDENT>kwargs['<STR_LIT>'] = project['<STR_LIT>']<EOL>kwargs['<STR_LIT>'] = project['<STR_LIT>']<EOL><DEDENT>itm, exc = func(*args, **kwargs)<EOL>item_list.extend(itm)<EOL>exception_map.update(exc)<EOL><DEDENT>return (item_list, exception_map)<EOL><DEDENT>return decorated_function<EOL><DEDENT>return decorator<EOL>

Call decorated function for each item in project list.

Note: the function 'decorated' is expected to return a value plus a dictionary of exceptions.

If item in list is a dictionary, we look for a 'project' and 'key_file' entry, respectively.
If item in list is of type string_types, we assume it is the project string. Default credentials
will be used by the underlying client library.

:param projects: list of project strings or list of dictionaries
                 Example: {'project':..., 'keyfile':...}. Required.
:type projects: ``list`` of ``str`` or ``list`` of ``dict``

:param key_file: path on disk to keyfile, for use with all projects
:type key_file: ``str``

:returns: tuple containing a list of function output and an exceptions map
:rtype: ``tuple of ``list``, ``dict``


service_account=kwargs.pop('<STR_LIT>')<EOL>resp = client.projects().serviceAccounts().get(<EOL>name=service_account).execute()<EOL>return resp<EOL>


service_account=kwargs.pop('<STR_LIT>')<EOL>kwargs['<STR_LIT:name>'] = service_account<EOL>return service_list(client.projects().serviceAccounts().keys(),<EOL>key_name='<STR_LIT>', **kwargs)<EOL>


service_account=kwargs.pop('<STR_LIT>')<EOL>resp = client.projects().serviceAccounts().getIamPolicy(<EOL>resource=service_account).execute()<EOL>if '<STR_LIT>' in resp:<EOL><INDENT>return resp['<STR_LIT>']<EOL><DEDENT>else:<EOL><INDENT>return None<EOL><DEDENT>


parts = module_name.split('<STR_LIT:.>')<EOL>short_name = module_name<EOL>for i in range(len(parts) - <NUM_LIT:1>, <NUM_LIT:0>, -<NUM_LIT:1>):<EOL><INDENT>short_name = '<STR_LIT:.>'.join(parts[:i])<EOL>try:<EOL><INDENT>exec('<STR_LIT>' % (short_name, obj_name))<EOL><DEDENT>except ImportError:<EOL><INDENT>short_name = '<STR_LIT:.>'.join(parts[:(i + <NUM_LIT:1>)])<EOL>break<EOL><DEDENT><DEDENT>return short_name<EOL>


finder = NameFinder()<EOL>finder.visit(ast.parse(code))<EOL>example_code_obj = {}<EOL>for name, full_name in finder.get_mapping():<EOL><INDENT>module, attribute = full_name.rsplit('<STR_LIT:.>', <NUM_LIT:1>)<EOL>module_short = get_short_module_name(module, attribute)<EOL>cobj = {'<STR_LIT:name>': attribute, '<STR_LIT>': module,<EOL>'<STR_LIT>': module_short}<EOL>example_code_obj[name] = cobj<EOL><DEDENT>return example_code_obj<EOL>

Builds a codeobj summary by identifying and resolving used names

    >>> code = '''
    ... from a.b import c
    ... import d as e
    ... print(c)
    ... e.HelloWorld().f.g
    ... '''
    >>> for name, o in sorted(identify_names(code).items()):
    ...     print(name, o['name'], o['module'], o['module_short'])
    c c a.b a.b
    e.HelloWorld HelloWorld d d


example_code_obj = identify_names(open(example_file).read())<EOL>if example_code_obj:<EOL><INDENT>codeobj_fname = example_file[:-<NUM_LIT:3>] + '<STR_LIT>'<EOL>with open(codeobj_fname, '<STR_LIT:wb>') as fid:<EOL><INDENT>pickle.dump(example_code_obj, fid, pickle.HIGHEST_PROTOCOL)<EOL><DEDENT><DEDENT>backrefs = set('<STR_LIT>'.format(**entry)<EOL>for entry in example_code_obj.values()<EOL>if entry['<STR_LIT>'].startswith(gallery_conf['<STR_LIT>']))<EOL>return backrefs<EOL>

save variables so we can later add links to the documentation


def _thumbnail_div(full_dir, fname, snippet, is_backref=False):

thumb = os.path.join(full_dir, '<STR_LIT>', '<STR_LIT>',<EOL>'<STR_LIT>' % fname[:-<NUM_LIT:3>])<EOL>ref_name = os.path.join(full_dir, fname).replace(os.path.sep, '<STR_LIT:_>')<EOL>template = BACKREF_THUMBNAIL_TEMPLATE if is_backref else THUMBNAIL_TEMPLATE<EOL>return template.format(snippet=snippet, thumbnail=thumb, ref_name=ref_name)<EOL>

Generates RST to place a thumbnail in a gallery


def write_backreferences(seen_backrefs, gallery_conf,<EOL>target_dir, fname, snippet):

example_file = os.path.join(target_dir, fname)<EOL>backrefs = scan_used_functions(example_file, gallery_conf)<EOL>for backref in backrefs:<EOL><INDENT>include_path = os.path.join(gallery_conf['<STR_LIT>'],<EOL>'<STR_LIT>' % backref)<EOL>seen = backref in seen_backrefs<EOL>with open(include_path, '<STR_LIT:a>' if seen else '<STR_LIT:w>') as ex_file:<EOL><INDENT>if not seen:<EOL><INDENT>heading = '<STR_LIT>' % backref<EOL>ex_file.write(heading + '<STR_LIT:\n>')<EOL>ex_file.write('<STR_LIT>' * len(heading) + '<STR_LIT:\n>')<EOL><DEDENT>ex_file.write(_thumbnail_div(target_dir, fname, snippet,<EOL>is_backref=True))<EOL>seen_backrefs.add(backref)<EOL><DEDENT><DEDENT>

Writes down back reference files, which include a thumbnail list
    of examples using a certain module


with open(filename) as f:<EOL><INDENT>content = f.read()<EOL><DEDENT>node = ast.parse(content)<EOL>if not isinstance(node, ast.Module):<EOL><INDENT>raise TypeError("<STR_LIT>"<EOL>"<STR_LIT>".format(node.__class__.__name__))<EOL><DEDENT>if node.body and isinstance(node.body[<NUM_LIT:0>], ast.Expr) andisinstance(node.body[<NUM_LIT:0>].value, ast.Str):<EOL><INDENT>docstring_node = node.body[<NUM_LIT:0>]<EOL>docstring = docstring_node.value.s<EOL>rest = content.split('<STR_LIT:\n>', docstring_node.lineno)[-<NUM_LIT:1>]<EOL>return docstring, rest<EOL><DEDENT>else:<EOL><INDENT>raise ValueError(('<STR_LIT>'<EOL>'<STR_LIT>')<EOL>.format(filename))<EOL><DEDENT>

Separate `filename` content between docstring and the rest

    Strongly inspired from ast.get_docstring.

    Returns
    -------
    docstring: str
        docstring of `filename`
    rest: str
        `filename` content without the docstring


docstring, rest_of_content = get_docstring_and_rest(source_file)<EOL>blocks = [('<STR_LIT:text>', docstring)]<EOL>pattern = re.compile(<EOL>r'<STR_LIT>',<EOL>flags=re.M)<EOL>pos_so_far = <NUM_LIT:0><EOL>for match in re.finditer(pattern, rest_of_content):<EOL><INDENT>match_start_pos, match_end_pos = match.span()<EOL>code_block_content = rest_of_content[pos_so_far:match_start_pos]<EOL>text_content = match.group('<STR_LIT>')<EOL>sub_pat = re.compile('<STR_LIT>', flags=re.M)<EOL>text_block_content = dedent(re.sub(sub_pat, '<STR_LIT>', text_content))<EOL>if code_block_content.strip():<EOL><INDENT>blocks.append(('<STR_LIT:code>', code_block_content))<EOL><DEDENT>if text_block_content.strip():<EOL><INDENT>blocks.append(('<STR_LIT:text>', text_block_content))<EOL><DEDENT>pos_so_far = match_end_pos<EOL><DEDENT>remaining_content = rest_of_content[pos_so_far:]<EOL>if remaining_content.strip():<EOL><INDENT>blocks.append(('<STR_LIT:code>', remaining_content))<EOL><DEDENT>return blocks<EOL>

Return list with source file separated into code and text blocks.

    Returns
    -------
    blocks : list of (label, content)
        List where each element is a tuple with the label ('text' or 'code'),
        and content string of block.


code_directive = "<STR_LIT>".format(lang)<EOL>indented_block = indent(codestr, '<STR_LIT:U+0020>' * <NUM_LIT:4>)<EOL>return code_directive + indented_block<EOL>

Return reStructuredText code block from code string


try:<EOL><INDENT>return ast.literal_eval(content) + '<STR_LIT:\n>'<EOL><DEDENT>except Exception:<EOL><INDENT>return content<EOL><DEDENT>

Returns a string without the extra triple quotes


docstring, _ = get_docstring_and_rest(filename)<EOL>paragraphs = docstring.lstrip().split('<STR_LIT>')<EOL>if len(paragraphs) > <NUM_LIT:1>:<EOL><INDENT>first_paragraph = re.sub('<STR_LIT:\n>', '<STR_LIT:U+0020>', paragraphs[<NUM_LIT:1>])<EOL>first_paragraph = (first_paragraph[:<NUM_LIT>] + '<STR_LIT>'<EOL>if len(first_paragraph) > <NUM_LIT> else first_paragraph)<EOL><DEDENT>else:<EOL><INDENT>raise ValueError(<EOL>"<STR_LIT>"<EOL>"<STR_LIT>"<EOL>"<STR_LIT>".format(filename))<EOL><DEDENT>return first_paragraph<EOL>

Extract the first paragraph of module-level docstring. max:95 char


with open(src_file, '<STR_LIT:r>') as src_data:<EOL><INDENT>src_content = src_data.read()<EOL>if sys.version_info[<NUM_LIT:0>] == <NUM_LIT:3>:<EOL><INDENT>src_content = src_content.encode('<STR_LIT:utf-8>')<EOL><DEDENT>src_md5 = hashlib.md5(src_content).hexdigest()<EOL><DEDENT>return src_md5<EOL>


src_md5 = get_md5sum(src_file)<EOL>src_md5_file = src_file + '<STR_LIT>'<EOL>src_file_changed = True<EOL>if os.path.exists(src_md5_file):<EOL><INDENT>with open(src_md5_file, '<STR_LIT:r>') as file_checksum:<EOL><INDENT>ref_md5 = file_checksum.read()<EOL><DEDENT>if src_md5 == ref_md5:<EOL><INDENT>src_file_changed = False<EOL><DEDENT><DEDENT>if src_file_changed:<EOL><INDENT>with open(src_md5_file, '<STR_LIT:w>') as file_checksum:<EOL><INDENT>file_checksum.write(src_md5)<EOL><DEDENT><DEDENT>return src_file_changed<EOL>

Returns True if src_file has a different md5sum


first_image_file = image_file.format(<NUM_LIT:1>)<EOL>has_image = os.path.exists(first_image_file)<EOL>src_file_changed = check_md5sum_change(src_file)<EOL>return has_image and not src_file_changed<EOL>

Test existence of image file and no change in md5sum of
    example


def save_figures(image_path, fig_count, gallery_conf):

figure_list = []<EOL>fig_managers = matplotlib._pylab_helpers.Gcf.get_all_fig_managers()<EOL>for fig_mngr in fig_managers:<EOL><INDENT>fig = plt.figure(fig_mngr.num)<EOL>kwargs = {}<EOL>to_rgba = matplotlib.colors.colorConverter.to_rgba<EOL>for attr in ['<STR_LIT>', '<STR_LIT>']:<EOL><INDENT>fig_attr = getattr(fig, '<STR_LIT>' + attr)()<EOL>default_attr = matplotlib.rcParams['<STR_LIT>' + attr]<EOL>if to_rgba(fig_attr) != to_rgba(default_attr):<EOL><INDENT>kwargs[attr] = fig_attr<EOL><DEDENT><DEDENT>current_fig = image_path.format(fig_count + fig_mngr.num)<EOL>fig.savefig(current_fig, **kwargs)<EOL>figure_list.append(current_fig)<EOL><DEDENT>if gallery_conf.get('<STR_LIT>', False):<EOL><INDENT>from mayavi import mlab<EOL>e = mlab.get_engine()<EOL>last_matplotlib_fig_num = len(figure_list)<EOL>total_fig_num = last_matplotlib_fig_num + len(e.scenes)<EOL>mayavi_fig_nums = range(last_matplotlib_fig_num, total_fig_num)<EOL>for scene, mayavi_fig_num in zip(e.scenes, mayavi_fig_nums):<EOL><INDENT>current_fig = image_path.format(mayavi_fig_num)<EOL>mlab.savefig(current_fig, figure=scene)<EOL>scale_image(current_fig, current_fig, <NUM_LIT>, <NUM_LIT>)<EOL>figure_list.append(current_fig)<EOL><DEDENT>mlab.close(all=True)<EOL><DEDENT>return figure_list<EOL>

Save all open matplotlib figures of the example code-block

    Parameters
    ----------
    image_path : str
        Path where plots are saved (format string which accepts figure number)
    fig_count : int
        Previous figure number count. Figure number add from this number

    Returns
    -------
    list of strings containing the full path to each figure


def scale_image(in_fname, out_fname, max_width, max_height):

<EOL>try:<EOL><INDENT>from PIL import Image<EOL><DEDENT>except ImportError:<EOL><INDENT>import Image<EOL><DEDENT>img = Image.open(in_fname)<EOL>width_in, height_in = img.size<EOL>scale_w = max_width / float(width_in)<EOL>scale_h = max_height / float(height_in)<EOL>if height_in * scale_w <= max_height:<EOL><INDENT>scale = scale_w<EOL><DEDENT>else:<EOL><INDENT>scale = scale_h<EOL><DEDENT>if scale >= <NUM_LIT:1.0> and in_fname == out_fname:<EOL><INDENT>return<EOL><DEDENT>width_sc = int(round(scale * width_in))<EOL>height_sc = int(round(scale * height_in))<EOL>img.thumbnail((width_sc, height_sc), Image.ANTIALIAS)<EOL>thumb = Image.new('<STR_LIT>', (max_width, max_height), (<NUM_LIT:255>, <NUM_LIT:255>, <NUM_LIT:255>))<EOL>pos_insert = ((max_width - width_sc) // <NUM_LIT:2>, (max_height - height_sc) // <NUM_LIT:2>)<EOL>thumb.paste(img, pos_insert)<EOL>thumb.save(out_fname)<EOL>if os.environ.get('<STR_LIT>', False):<EOL><INDENT>try:<EOL><INDENT>subprocess.call(["<STR_LIT>", "<STR_LIT>", "<STR_LIT>", "<STR_LIT>", out_fname])<EOL><DEDENT>except Exception:<EOL><INDENT>warnings.warn('<STR_LIT>')<EOL><DEDENT><DEDENT>

Scales an image with the same aspect ratio centered in an
       image with a given max_width and max_height
       if in_fname == out_fname the image can only be scaled down


def save_thumbnail(image_path, base_image_name, gallery_conf):

first_image_file = image_path.format(<NUM_LIT:1>)<EOL>thumb_dir = os.path.join(os.path.dirname(first_image_file), '<STR_LIT>')<EOL>if not os.path.exists(thumb_dir):<EOL><INDENT>os.makedirs(thumb_dir)<EOL><DEDENT>thumb_file = os.path.join(thumb_dir,<EOL>'<STR_LIT>' % base_image_name)<EOL>if os.path.exists(first_image_file):<EOL><INDENT>scale_image(first_image_file, thumb_file, <NUM_LIT>, <NUM_LIT>)<EOL><DEDENT>elif not os.path.exists(thumb_file):<EOL><INDENT>default_thumb_file = os.path.join(glr_path_static(), '<STR_LIT>')<EOL>default_thumb_file = gallery_conf.get("<STR_LIT>",<EOL>default_thumb_file)<EOL>scale_image(default_thumb_file, thumb_file, <NUM_LIT:200>, <NUM_LIT>)<EOL><DEDENT>


def generate_dir_rst(src_dir, target_dir, gallery_conf, seen_backrefs):

if not os.path.exists(os.path.join(src_dir, '<STR_LIT>')):<EOL><INDENT>print(<NUM_LIT> * '<STR_LIT:_>')<EOL>print('<STR_LIT>' %<EOL>src_dir)<EOL>print('<STR_LIT>')<EOL>print(<NUM_LIT> * '<STR_LIT:_>')<EOL>return "<STR_LIT>"  <EOL><DEDENT>fhindex = open(os.path.join(src_dir, '<STR_LIT>')).read()<EOL>if not os.path.exists(target_dir):<EOL><INDENT>os.makedirs(target_dir)<EOL><DEDENT>sorted_listdir = [fname for fname in sorted(os.listdir(src_dir))<EOL>if fname.endswith('<STR_LIT>')]<EOL>entries_text = []<EOL>for fname in sorted_listdir:<EOL><INDENT>amount_of_code = generate_file_rst(fname, target_dir, src_dir,<EOL>gallery_conf)<EOL>new_fname = os.path.join(src_dir, fname)<EOL>intro = extract_intro(new_fname)<EOL>write_backreferences(seen_backrefs, gallery_conf,<EOL>target_dir, fname, intro)<EOL>this_entry = _thumbnail_div(target_dir, fname, intro) + """<STR_LIT>""" % (target_dir, fname[:-<NUM_LIT:3>])<EOL>entries_text.append((amount_of_code, this_entry))<EOL><DEDENT>entries_text.sort()<EOL>for _, entry_text in entries_text:<EOL><INDENT>fhindex += entry_text<EOL><DEDENT>fhindex += """<STR_LIT>"""<EOL>return fhindex<EOL>

Generate the gallery reStructuredText for an example directory


def execute_script(code_block, example_globals, image_path, fig_count,<EOL>src_file, gallery_conf):

time_elapsed = <NUM_LIT:0><EOL>stdout = '<STR_LIT>'<EOL>print('<STR_LIT>' % src_file)<EOL>plt.close('<STR_LIT:all>')<EOL>cwd = os.getcwd()<EOL>orig_stdout = sys.stdout<EOL>try:<EOL><INDENT>os.chdir(os.path.dirname(src_file))<EOL>my_buffer = StringIO()<EOL>my_stdout = Tee(sys.stdout, my_buffer)<EOL>sys.stdout = my_stdout<EOL>t_start = time()<EOL>exec(code_block, example_globals)<EOL>time_elapsed = time() - t_start<EOL>sys.stdout = orig_stdout<EOL>my_stdout = my_buffer.getvalue().strip().expandtabs()<EOL>if my_stdout:<EOL><INDENT>stdout = CODE_OUTPUT.format(indent(my_stdout, '<STR_LIT:U+0020>' * <NUM_LIT:4>))<EOL><DEDENT>os.chdir(cwd)<EOL>figure_list = save_figures(image_path, fig_count, gallery_conf)<EOL>image_list = "<STR_LIT>"<EOL>if len(figure_list) == <NUM_LIT:1>:<EOL><INDENT>figure_name = figure_list[<NUM_LIT:0>]<EOL>image_list = SINGLE_IMAGE % figure_name.lstrip('<STR_LIT:/>')<EOL><DEDENT>elif len(figure_list) > <NUM_LIT:1>:<EOL><INDENT>image_list = HLIST_HEADER<EOL>for figure_name in figure_list:<EOL><INDENT>image_list += HLIST_IMAGE_TEMPLATE % figure_name.lstrip('<STR_LIT:/>')<EOL><DEDENT><DEDENT><DEDENT>except Exception:<EOL><INDENT>formatted_exception = traceback.format_exc()<EOL>print(<NUM_LIT> * '<STR_LIT:_>')<EOL>print('<STR_LIT>' % src_file)<EOL>print(formatted_exception)<EOL>print(<NUM_LIT> * '<STR_LIT:_>')<EOL>figure_list = []<EOL>image_list = codestr2rst(formatted_exception, lang='<STR_LIT>')<EOL>broken_img = os.path.join(glr_path_static(), '<STR_LIT>')<EOL>shutil.copyfile(broken_img, os.path.join(cwd, image_path.format(<NUM_LIT:1>)))<EOL>fig_count += <NUM_LIT:1>  <EOL>if gallery_conf['<STR_LIT>']:<EOL><INDENT>raise<EOL><DEDENT><DEDENT>finally:<EOL><INDENT>os.chdir(cwd)<EOL>sys.stdout = orig_stdout<EOL><DEDENT>print("<STR_LIT>" % time_elapsed)<EOL>code_output = "<STR_LIT>".format(image_list, stdout)<EOL>return code_output, time_elapsed, fig_count + len(figure_list)<EOL>

Executes the code block of the example file


def generate_file_rst(fname, target_dir, src_dir, gallery_conf):

src_file = os.path.join(src_dir, fname)<EOL>example_file = os.path.join(target_dir, fname)<EOL>shutil.copyfile(src_file, example_file)<EOL>image_dir = os.path.join(target_dir, '<STR_LIT>')<EOL>if not os.path.exists(image_dir):<EOL><INDENT>os.makedirs(image_dir)<EOL><DEDENT>base_image_name = os.path.splitext(fname)[<NUM_LIT:0>]<EOL>image_fname = '<STR_LIT>' + base_image_name + '<STR_LIT>'<EOL>image_path = os.path.join(image_dir, image_fname)<EOL>script_blocks = split_code_and_text_blocks(example_file)<EOL>amount_of_code = sum([len(bcontent)<EOL>for blabel, bcontent in script_blocks<EOL>if blabel == '<STR_LIT:code>'])<EOL>if _plots_are_current(example_file, image_path):<EOL><INDENT>return amount_of_code<EOL><DEDENT>time_elapsed = <NUM_LIT:0><EOL>ref_fname = example_file.replace(os.path.sep, '<STR_LIT:_>')<EOL>example_rst = """<STR_LIT>""".format(ref_fname)<EOL>example_nb = Notebook(fname, target_dir)<EOL>filename_pattern = gallery_conf.get('<STR_LIT>')<EOL>if re.search(filename_pattern, src_file) and gallery_conf['<STR_LIT>']:<EOL><INDENT>example_globals = {'<STR_LIT>': '<STR_LIT>'}<EOL>fig_count = <NUM_LIT:0><EOL>is_example_notebook_like = len(script_blocks) > <NUM_LIT:2><EOL>for blabel, bcontent in script_blocks:<EOL><INDENT>if blabel == '<STR_LIT:code>':<EOL><INDENT>code_output, rtime, fig_count = execute_script(bcontent,<EOL>example_globals,<EOL>image_path,<EOL>fig_count,<EOL>src_file,<EOL>gallery_conf)<EOL>time_elapsed += rtime<EOL>example_nb.add_code_cell(bcontent)<EOL>if is_example_notebook_like:<EOL><INDENT>example_rst += codestr2rst(bcontent) + '<STR_LIT:\n>'<EOL>example_rst += code_output<EOL><DEDENT>else:<EOL><INDENT>example_rst += code_output<EOL>example_rst += codestr2rst(bcontent) + '<STR_LIT:\n>'<EOL><DEDENT><DEDENT>else:<EOL><INDENT>example_rst += text2string(bcontent) + '<STR_LIT:\n>'<EOL>example_nb.add_markdown_cell(text2string(bcontent))<EOL><DEDENT><DEDENT><DEDENT>else:<EOL><INDENT>for blabel, bcontent in script_blocks:<EOL><INDENT>if blabel == '<STR_LIT:code>':<EOL><INDENT>example_rst += codestr2rst(bcontent) + '<STR_LIT:\n>'<EOL>example_nb.add_code_cell(bcontent)<EOL><DEDENT>else:<EOL><INDENT>example_rst += bcontent + '<STR_LIT:\n>'<EOL>example_nb.add_markdown_cell(text2string(bcontent))<EOL><DEDENT><DEDENT><DEDENT>save_thumbnail(image_path, base_image_name, gallery_conf)<EOL>time_m, time_s = divmod(time_elapsed, <NUM_LIT>)<EOL>example_nb.save_file()<EOL>with open(os.path.join(target_dir, base_image_name + '<STR_LIT>'), '<STR_LIT:w>') as f:<EOL><INDENT>example_rst += CODE_DOWNLOAD.format(time_m, time_s, fname,<EOL>example_nb.file_name)<EOL>f.write(example_rst)<EOL><DEDENT>return amount_of_code<EOL>

Generate the rst file for a given example.

        Returns the amout of code (in characters) of the corresponding
        files.


return os.path.abspath(os.path.join(os.path.dirname(__file__), '<STR_LIT>'))<EOL>


try:<EOL><INDENT>plot_gallery = eval(app.builder.config.plot_gallery)<EOL><DEDENT>except TypeError:<EOL><INDENT>plot_gallery = bool(app.builder.config.plot_gallery)<EOL><DEDENT>gallery_conf.update(app.config.sphinx_gallery_conf)<EOL>gallery_conf.update(plot_gallery=plot_gallery)<EOL>gallery_conf.update(abort_on_example_error=app.builder.config.abort_on_example_error)<EOL>app.config.sphinx_gallery_conf = gallery_conf<EOL>app.config.html_static_path.append(glr_path_static())<EOL>clean_gallery_out(app.builder.outdir)<EOL>examples_dirs = gallery_conf['<STR_LIT>']<EOL>gallery_dirs = gallery_conf['<STR_LIT>']<EOL>if not isinstance(examples_dirs, list):<EOL><INDENT>examples_dirs = [examples_dirs]<EOL><DEDENT>if not isinstance(gallery_dirs, list):<EOL><INDENT>gallery_dirs = [gallery_dirs]<EOL><DEDENT>mod_examples_dir = os.path.relpath(gallery_conf['<STR_LIT>'],<EOL>app.builder.srcdir)<EOL>seen_backrefs = set()<EOL>for examples_dir, gallery_dir in zip(examples_dirs, gallery_dirs):<EOL><INDENT>examples_dir = os.path.relpath(examples_dir,<EOL>app.builder.srcdir)<EOL>gallery_dir = os.path.relpath(gallery_dir,<EOL>app.builder.srcdir)<EOL>for workdir in [examples_dir, gallery_dir, mod_examples_dir]:<EOL><INDENT>if not os.path.exists(workdir):<EOL><INDENT>os.makedirs(workdir)<EOL><DEDENT><DEDENT>fhindex = open(os.path.join(gallery_dir, '<STR_LIT>'), '<STR_LIT:w>')<EOL>fhindex.write(generate_dir_rst(examples_dir, gallery_dir, gallery_conf,<EOL>seen_backrefs))<EOL>for directory in sorted(os.listdir(examples_dir)):<EOL><INDENT>if os.path.isdir(os.path.join(examples_dir, directory)):<EOL><INDENT>src_dir = os.path.join(examples_dir, directory)<EOL>target_dir = os.path.join(gallery_dir, directory)<EOL>fhindex.write(generate_dir_rst(src_dir, target_dir,<EOL>gallery_conf,<EOL>seen_backrefs))<EOL><DEDENT><DEDENT>fhindex.flush()<EOL><DEDENT>

Generate the Main examples gallery reStructuredText

    Start the sphinx-gallery configuration and recursively scan the examples
    directories in order to populate the examples gallery


app.add_config_value('<STR_LIT>', True, '<STR_LIT:html>')<EOL>app.add_config_value('<STR_LIT>', False, '<STR_LIT:html>')<EOL>app.add_config_value('<STR_LIT>', gallery_conf, '<STR_LIT:html>')<EOL>app.add_stylesheet('<STR_LIT>')<EOL>app.connect('<STR_LIT>', generate_gallery_rst)<EOL>app.connect('<STR_LIT>', embed_code_links)<EOL>


py_version = sys.version_info<EOL>notebook_skeleton = {<EOL>"<STR_LIT>": [],<EOL>"<STR_LIT>": {<EOL>"<STR_LIT>": {<EOL>"<STR_LIT>": "<STR_LIT>" + str(py_version[<NUM_LIT:0>]),<EOL>"<STR_LIT>": "<STR_LIT>",<EOL>"<STR_LIT:name>": "<STR_LIT>" + str(py_version[<NUM_LIT:0>])<EOL>},<EOL>"<STR_LIT>": {<EOL>"<STR_LIT>": {<EOL>"<STR_LIT:name>": "<STR_LIT>",<EOL>"<STR_LIT:version>": py_version[<NUM_LIT:0>]<EOL>},<EOL>"<STR_LIT>": "<STR_LIT>",<EOL>"<STR_LIT>": "<STR_LIT>",<EOL>"<STR_LIT:name>": "<STR_LIT>",<EOL>"<STR_LIT>": "<STR_LIT>",<EOL>"<STR_LIT>": "<STR_LIT>" + str(py_version[<NUM_LIT:0>]),<EOL>"<STR_LIT:version>": '<STR_LIT>'.format(*sys.version_info[:<NUM_LIT:3>])<EOL>}<EOL>},<EOL>"<STR_LIT>": <NUM_LIT:4>,<EOL>"<STR_LIT>": <NUM_LIT:0><EOL>}<EOL>return notebook_skeleton<EOL>

Returns a dictionary with the elements of a Jupyter notebook


top_heading = re.compile(r'<STR_LIT>', flags=re.M)<EOL>text = re.sub(top_heading, r'<STR_LIT>', text)<EOL>math_eq = re.compile(r'<STR_LIT>', flags=re.M)<EOL>text = re.sub(math_eq,<EOL>lambda match: r'<STR_LIT>'.format(match.group(<NUM_LIT:1>).strip()),<EOL>text)<EOL>inline_math = re.compile(r'<STR_LIT>')<EOL>text = re.sub(inline_math, r'<STR_LIT>', text)<EOL>return text<EOL>

Converts the RST text from the examples docstrigs and comments
    into markdown text for the IPython notebooks


def __init__(self, file_name, target_dir):

self.file_name = file_name.replace('<STR_LIT>', '<STR_LIT>')<EOL>self.write_file = os.path.join(target_dir, self.file_name)<EOL>self.work_notebook = ipy_notebook_skeleton()<EOL>self.add_code_cell("<STR_LIT>")<EOL>

Declare the skeleton of the notebook

        Parameters
        ----------
        file_name : str
            original script file name, .py extension will be renamed
        target_dir: str
            directory where notebook file is to be saved


code_cell = {<EOL>"<STR_LIT>": "<STR_LIT:code>",<EOL>"<STR_LIT>": None,<EOL>"<STR_LIT>": {"<STR_LIT>": False},<EOL>"<STR_LIT>": [],<EOL>"<STR_LIT:source>": [code.strip()]<EOL>}<EOL>self.work_notebook["<STR_LIT>"].append(code_cell)<EOL>

Add a code cell to the notebook

        Parameters
        ----------
        code : str
            Cell content


markdown_cell = {<EOL>"<STR_LIT>": "<STR_LIT>",<EOL>"<STR_LIT>": {},<EOL>"<STR_LIT:source>": [rst2md(text)]<EOL>}<EOL>self.work_notebook["<STR_LIT>"].append(markdown_cell)<EOL>

Add a markdown cell to the notebook

        Parameters
        ----------
        code : str
            Cell content


with open(self.write_file, '<STR_LIT:w>') as out_nb:<EOL><INDENT>json.dump(self.work_notebook, out_nb, indent=<NUM_LIT:2>)<EOL><DEDENT>


if url.startswith('<STR_LIT>'):<EOL><INDENT>try:<EOL><INDENT>resp = urllib.urlopen(url)<EOL>encoding = resp.headers.dict.get('<STR_LIT>', '<STR_LIT>')<EOL><DEDENT>except AttributeError:<EOL><INDENT>resp = urllib.request.urlopen(url)<EOL>encoding = resp.headers.get('<STR_LIT>', '<STR_LIT>')<EOL><DEDENT>data = resp.read()<EOL>if encoding == '<STR_LIT>':<EOL><INDENT>pass<EOL><DEDENT>elif encoding == '<STR_LIT>':<EOL><INDENT>data = StringIO(data)<EOL>data = gzip.GzipFile(fileobj=data).read()<EOL><DEDENT>else:<EOL><INDENT>raise RuntimeError('<STR_LIT>')<EOL><DEDENT><DEDENT>else:<EOL><INDENT>with open(url, '<STR_LIT:r>') as fid:<EOL><INDENT>data = fid.read()<EOL><DEDENT><DEDENT>return data<EOL>

Helper function to get data over http or from a local file


<EOL>if sys.version_info[<NUM_LIT:0>] == <NUM_LIT:2> and isinstance(url, unicode):<EOL><INDENT>url = url.encode('<STR_LIT:utf-8>')<EOL><DEDENT>cached_file = os.path.join(gallery_dir, '<STR_LIT>')<EOL>search_index = shelve.open(cached_file)<EOL>if url in search_index:<EOL><INDENT>data = search_index[url]<EOL><DEDENT>else:<EOL><INDENT>data = _get_data(url)<EOL>search_index[url] = data<EOL><DEDENT>search_index.close()<EOL>return data<EOL>

Persistent dictionary usage to retrieve the search indexes


def _select_block(str_in, start_tag, end_tag):

start_pos = str_in.find(start_tag)<EOL>if start_pos < <NUM_LIT:0>:<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT>depth = <NUM_LIT:0><EOL>for pos in range(start_pos, len(str_in)):<EOL><INDENT>if str_in[pos] == start_tag:<EOL><INDENT>depth += <NUM_LIT:1><EOL><DEDENT>elif str_in[pos] == end_tag:<EOL><INDENT>depth -= <NUM_LIT:1><EOL><DEDENT>if depth == <NUM_LIT:0>:<EOL><INDENT>break<EOL><DEDENT><DEDENT>sel = str_in[start_pos + <NUM_LIT:1>:pos]<EOL>return sel<EOL>

Select first block delimited by start_tag and end_tag


dict_out = dict()<EOL>pos_last = <NUM_LIT:0><EOL>pos = dict_str.find('<STR_LIT::>')<EOL>while pos >= <NUM_LIT:0>:<EOL><INDENT>key = dict_str[pos_last:pos]<EOL>if dict_str[pos + <NUM_LIT:1>] == '<STR_LIT:[>':<EOL><INDENT>pos_tmp = dict_str.find('<STR_LIT:]>', pos + <NUM_LIT:1>)<EOL>if pos_tmp < <NUM_LIT:0>:<EOL><INDENT>raise RuntimeError('<STR_LIT>')<EOL><DEDENT>value = dict_str[pos + <NUM_LIT:2>: pos_tmp].split('<STR_LIT:U+002C>')<EOL>for i in range(len(value)):<EOL><INDENT>try:<EOL><INDENT>value[i] = int(value[i])<EOL><DEDENT>except ValueError:<EOL><INDENT>pass<EOL><DEDENT><DEDENT><DEDENT>elif dict_str[pos + <NUM_LIT:1>] == '<STR_LIT:{>':<EOL><INDENT>subdict_str = _select_block(dict_str[pos:], '<STR_LIT:{>', '<STR_LIT:}>')<EOL>value = _parse_dict_recursive(subdict_str)<EOL>pos_tmp = pos + len(subdict_str)<EOL><DEDENT>else:<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT>key = key.strip('<STR_LIT:">')<EOL>if len(key) > <NUM_LIT:0>:<EOL><INDENT>dict_out[key] = value<EOL><DEDENT>pos_last = dict_str.find('<STR_LIT:U+002C>', pos_tmp)<EOL>if pos_last < <NUM_LIT:0>:<EOL><INDENT>break<EOL><DEDENT>pos_last += <NUM_LIT:1><EOL>pos = dict_str.find('<STR_LIT::>', pos_last)<EOL><DEDENT>return dict_out<EOL>

Parse a dictionary from the search index


<EOL>if hasattr(searchindex, '<STR_LIT>'):<EOL><INDENT>searchindex = searchindex.decode('<STR_LIT>')<EOL><DEDENT>query = '<STR_LIT>'<EOL>pos = searchindex.find(query)<EOL>if pos < <NUM_LIT:0>:<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT>sel = _select_block(searchindex[pos:], '<STR_LIT:{>', '<STR_LIT:}>')<EOL>objects = _parse_dict_recursive(sel)<EOL>query = '<STR_LIT>'<EOL>pos = searchindex.find(query)<EOL>if pos < <NUM_LIT:0>:<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT>filenames = searchindex[pos + len(query) + <NUM_LIT:1>:]<EOL>filenames = filenames[:filenames.find('<STR_LIT:]>')]<EOL>filenames = [f.strip('<STR_LIT:">') for f in filenames.split('<STR_LIT:U+002C>')]<EOL>return filenames, objects<EOL>

Parse a Sphinx search index

    Parameters
    ----------
    searchindex : str
        The Sphinx search index (contents of searchindex.js)

    Returns
    -------
    filenames : list of str
        The file names parsed from the search index.
    objects : dict
        The objects parsed from the search index.


if exception is not None:<EOL><INDENT>return<EOL><DEDENT>if not app.builder.config.plot_gallery:<EOL><INDENT>return<EOL><DEDENT>if app.builder.name not in ['<STR_LIT:html>', '<STR_LIT>']:<EOL><INDENT>return<EOL><DEDENT>print('<STR_LIT>')<EOL>gallery_conf = app.config.sphinx_gallery_conf<EOL>gallery_dirs = gallery_conf['<STR_LIT>']<EOL>if not isinstance(gallery_dirs, list):<EOL><INDENT>gallery_dirs = [gallery_dirs]<EOL><DEDENT>for gallery_dir in gallery_dirs:<EOL><INDENT>_embed_code_links(app, gallery_conf, gallery_dir)<EOL><DEDENT>

Embed hyperlinks to documentation into example code


fname_idx = None<EOL>full_name = cobj['<STR_LIT>'] + '<STR_LIT:.>' + cobj['<STR_LIT:name>']<EOL>if full_name in self._searchindex['<STR_LIT>']:<EOL><INDENT>value = self._searchindex['<STR_LIT>'][full_name]<EOL>if isinstance(value, dict):<EOL><INDENT>value = value[next(iter(value.keys()))]<EOL><DEDENT>fname_idx = value[<NUM_LIT:0>]<EOL><DEDENT>elif cobj['<STR_LIT>'] in self._searchindex['<STR_LIT>']:<EOL><INDENT>value = self._searchindex['<STR_LIT>'][cobj['<STR_LIT>']]<EOL>if cobj['<STR_LIT:name>'] in value.keys():<EOL><INDENT>fname_idx = value[cobj['<STR_LIT:name>']][<NUM_LIT:0>]<EOL><DEDENT><DEDENT>if fname_idx is not None:<EOL><INDENT>fname = self._searchindex['<STR_LIT>'][fname_idx] + '<STR_LIT>'<EOL>if self._is_windows:<EOL><INDENT>fname = fname.replace('<STR_LIT:/>', '<STR_LIT:\\>')<EOL>link = os.path.join(self.doc_url, fname)<EOL><DEDENT>else:<EOL><INDENT>link = posixpath.join(self.doc_url, fname)<EOL><DEDENT>if hasattr(link, '<STR_LIT>'):<EOL><INDENT>link = link.decode('<STR_LIT:utf-8>', '<STR_LIT:replace>')<EOL><DEDENT>if link in self._page_cache:<EOL><INDENT>html = self._page_cache[link]<EOL><DEDENT>else:<EOL><INDENT>html = get_data(link, self.gallery_dir)<EOL>self._page_cache[link] = html<EOL><DEDENT>comb_names = [cobj['<STR_LIT>'] + '<STR_LIT:.>' + cobj['<STR_LIT:name>']]<EOL>if self.extra_modules_test is not None:<EOL><INDENT>for mod in self.extra_modules_test:<EOL><INDENT>comb_names.append(mod + '<STR_LIT:.>' + cobj['<STR_LIT:name>'])<EOL><DEDENT><DEDENT>url = False<EOL>if hasattr(html, '<STR_LIT>'):<EOL><INDENT>html = html.decode('<STR_LIT:utf-8>', '<STR_LIT:replace>')<EOL><DEDENT>for comb_name in comb_names:<EOL><INDENT>if hasattr(comb_name, '<STR_LIT>'):<EOL><INDENT>comb_name = comb_name.decode('<STR_LIT:utf-8>', '<STR_LIT:replace>')<EOL><DEDENT>if comb_name in html:<EOL><INDENT>url = link + u'<STR_LIT:#>' + comb_name<EOL><DEDENT><DEDENT>link = url<EOL><DEDENT>else:<EOL><INDENT>link = False<EOL><DEDENT>return link<EOL>


full_name = cobj['<STR_LIT>'] + '<STR_LIT:.>' + cobj['<STR_LIT:name>']<EOL>link = self._link_cache.get(full_name, None)<EOL>if link is None:<EOL><INDENT>link = self._get_link(cobj)<EOL>self._link_cache[full_name] = link<EOL><DEDENT>if link is False or link is None:<EOL><INDENT>return None<EOL><DEDENT>if self.relative:<EOL><INDENT>link = os.path.relpath(link, start=this_url)<EOL>if self._is_windows:<EOL><INDENT>link = link.replace('<STR_LIT:\\>', '<STR_LIT:/>')<EOL><DEDENT>link = link[<NUM_LIT:3>:]<EOL><DEDENT>return link<EOL>

Resolve the link to the documentation, returns None if not found

        Parameters
        ----------
        cobj : dict
            Dict with information about the "code object" for which we are
            resolving a link.
            cobi['name'] : function or class name (str)
            cobj['module_short'] : shortened module name (str)
            cobj['module'] : module name (str)
        this_url: str
            URL of the current page. Needed to construct relative URLs
            (only used if relative=True in constructor).

        Returns
        -------
        link : str | None
            The link (URL) to the documentation.


errors.is_positive_integer(n)<EOL>result = numpy.zeros((n, n))<EOL>for i in range(<NUM_LIT:0>, n):<EOL><INDENT>result[i, <NUM_LIT:0>] = <NUM_LIT:1><EOL>result[<NUM_LIT:0>, i] = <NUM_LIT:1><EOL><DEDENT>if n > <NUM_LIT:1>:<EOL><INDENT>for i in range(<NUM_LIT:1>, n):<EOL><INDENT>for j in range(<NUM_LIT:1>, n):<EOL><INDENT>result[i, j] = result[i-<NUM_LIT:1>, j] + result[i, j-<NUM_LIT:1>]<EOL><DEDENT><DEDENT><DEDENT>return result<EOL>


def corrmtx(x_input, m, method='<STR_LIT>'):

valid_methods = ['<STR_LIT>', '<STR_LIT>', '<STR_LIT>',<EOL>'<STR_LIT>', '<STR_LIT>']<EOL>if method not in valid_methods:<EOL><INDENT>raise ValueError("<STR_LIT>" % valid_methods)<EOL><DEDENT>from scipy.linalg import toeplitz<EOL>N = len(x_input)<EOL>if isinstance(x_input, list):<EOL><INDENT>x = numpy.array(x_input)<EOL><DEDENT>else:<EOL><INDENT>x = x_input.copy()<EOL><DEDENT>if x.dtype == complex:<EOL><INDENT>complex_type = True<EOL><DEDENT>else:<EOL><INDENT>complex_type = False<EOL><DEDENT>if method in ['<STR_LIT>', '<STR_LIT>']:<EOL><INDENT>Lp = toeplitz(x[<NUM_LIT:0>:m], [<NUM_LIT:0>]*(m+<NUM_LIT:1>))<EOL><DEDENT>Tp = toeplitz(x[m:N], x[m::-<NUM_LIT:1>])<EOL>if method in ['<STR_LIT>', '<STR_LIT>']:<EOL><INDENT>Up = toeplitz([<NUM_LIT:0>]*(m+<NUM_LIT:1>), numpy.insert(x[N:N-m-<NUM_LIT:1>:-<NUM_LIT:1>],<NUM_LIT:0>,<NUM_LIT:0>))<EOL><DEDENT>if method == '<STR_LIT>':<EOL><INDENT>if complex_type == True:<EOL><INDENT>C = numpy.zeros((N+m, m+<NUM_LIT:1>), dtype=complex)<EOL><DEDENT>else:<EOL><INDENT>C = numpy.zeros((N+m, m+<NUM_LIT:1>))<EOL><DEDENT>for i in range(<NUM_LIT:0>, m):<EOL><INDENT>C[i] = Lp[i]<EOL><DEDENT>for i in range(m, N):<EOL><INDENT>C[i] = Tp[i-m]<EOL><DEDENT>for i in range(N, N+m):<EOL><INDENT>C[i] = Up[i-N]<EOL><DEDENT><DEDENT>elif method == '<STR_LIT>':<EOL><INDENT>if complex_type == True:<EOL><INDENT>C = numpy.zeros((N, m+<NUM_LIT:1>), dtype=complex)<EOL><DEDENT>else:<EOL><INDENT>C = numpy.zeros((N, m+<NUM_LIT:1>))<EOL><DEDENT>for i in range(<NUM_LIT:0>, m):<EOL><INDENT>C[i] = Lp[i]<EOL><DEDENT>for i in range(m, N):<EOL><INDENT>C[i] = Tp[i-m]<EOL><DEDENT><DEDENT>elif method == '<STR_LIT>':<EOL><INDENT>if complex_type == True:<EOL><INDENT>C = numpy.zeros((N, m+<NUM_LIT:1>), dtype=complex)<EOL><DEDENT>else:<EOL><INDENT>C = numpy.zeros((N, m+<NUM_LIT:1>))<EOL><DEDENT>for i in range(<NUM_LIT:0>, N-m):<EOL><INDENT>C[i] = Tp[i]<EOL><DEDENT>for i in range(N-m, N):<EOL><INDENT>C[i] = Up[i-N+m]<EOL><DEDENT><DEDENT>elif method == '<STR_LIT>':<EOL><INDENT>return Tp<EOL><DEDENT>elif method == '<STR_LIT>':<EOL><INDENT>if complex_type == True:<EOL><INDENT>C = numpy.zeros((<NUM_LIT:2>*(N-m), m+<NUM_LIT:1>), dtype=complex)<EOL><DEDENT>else:<EOL><INDENT>C = numpy.zeros((<NUM_LIT:2>*(N-m), m+<NUM_LIT:1>))<EOL><DEDENT>for i in range(<NUM_LIT:0>, N-m):<EOL><INDENT>C[i] = Tp[i]<EOL><DEDENT>Tp = numpy.fliplr(Tp.conj())<EOL>for i in range(N-m, <NUM_LIT:2>*(N-m)):<EOL><INDENT>C[i] = Tp[i-N+m]<EOL><DEDENT><DEDENT>return C<EOL>

r"""Correlation matrix

    This function is used by PSD estimator functions. It generates
    the correlation matrix from a correlation data set and a maximum lag.

    :param array x: autocorrelation samples (1D)
    :param int m: the maximum lag

    Depending on the choice of the method, the correlation matrix has different
    sizes, but the number of rows is always m+1.

    Method can be :

    * 'autocorrelation': (default) X is the (n+m)-by-(m+1) rectangular Toeplitz
      matrix derived using prewindowed and postwindowed data.
    * 'prewindowed': X is the n-by-(m+1) rectangular Toeplitz matrix derived
      using prewindowed data only.
    * 'postwindowed': X is the n-by-(m+1) rectangular Toeplitz matrix that
      derived using postwindowed data only.
    * 'covariance': X is the (n-m)-by-(m+1) rectangular Toeplitz matrix
      derived using nonwindowed data.
    * 'modified': X is the 2(n-m)-by-(m+1) modified rectangular Toeplitz
      matrix that generates an autocorrelation estimate for the length n data
      vector x, derived using forward and backward prediction error estimates.

    :return:
        * the autocorrelation matrix
        * R, the (m+1)-by-(m+1) autocorrelation matrix estimate ``R= X'*X``.

    .. rubric:: Algorithm details:

    The **autocorrelation** matrix is a :math:`(N+p) \times (p+1)` rectangular Toeplilz
    data matrix:

    .. math:: X_p = \begin{pmatrix}L_p\\T_p\\Up\end{pmatrix}

    where the lower triangular :math:`p \times (p+1)` matrix :math:`L_p` is

    .. math:: L_p =
        \begin{pmatrix}
        x[1]     &  \cdots     & 0     & 0        \\
        \vdots    &  \ddots     & \vdots & \vdots    \\
        x[p]     &  \cdots     & x[1]  & 0
        \end{pmatrix}

    where the rectangular :math:`(N-p) \times (p+1)` matrix :math:`T_p` is

    .. math:: T_p =
        \begin{pmatrix}
        x[p+1]     &  \cdots    & x[1]        \\
        \vdots    &  \ddots     & \vdots    \\
        x[N-p]     &  \cdots    & x[p+1]        \\
        \vdots    &  \ddots     & \vdots    \\
        x[N]     &  \cdots      & x[N-p]
        \end{pmatrix}

    and where the upper triangular :math:`p \times (p+1)` matrix :math:`U_p` is

    .. math:: U_p =
        \begin{pmatrix}
        0         &  x[N]      & \cdots     & x[N-p+1]        \\
        \vdots    &  \vdots    & \ddots & \vdots    \\
        0         &  0         & \cdots  & x[N]
        \end{pmatrix}

    From this definition, the prewindowed matrix is

    .. math:: X_p = \begin{pmatrix}L_p\\T_p\end{pmatrix}

    the postwindowed matrix is

    .. math:: X_p = \begin{pmatrix}T_p\\U_p\end{pmatrix}

    the covariance matrix is:

    .. math:: X_p = \begin{pmatrix}T_p\end{pmatrix}

    and the modified covariance matrix is:

    .. math:: X_p = \begin{pmatrix}T_p\\T_p^*\end{pmatrix}


U, S, V = numpy.linalg.svd(A)<EOL>return U, S, V<EOL>

SVD decomposition using numpy.linalg.svd

    :param A: a M by N matrix

    :return:
        * U, a M by M matrix
        * S the N eigen values
        * V a N by N matrix

    See :func:`numpy.linalg.svd` for a detailed documentation.

    Should return the same as in [Marple]_ , CSVD routine.

    ::

        U, S, V = numpy.linalg.svd(A)
        U, S, V = cvsd(A)


return np.sqrt(np.mean(np.absolute(a) ** <NUM_LIT:2>))<EOL>

Return the root mean square of all the elements of *a*, flattened out.
(Copied 1:1 from matplotlib.mlab.)


def CORRELATION(x, y=None, maxlags=None, norm='<STR_LIT>'):

assert norm in ['<STR_LIT>','<STR_LIT>', '<STR_LIT>', None]<EOL>x = np.array(x)<EOL>if y is None:<EOL><INDENT>y = x<EOL><DEDENT>else:<EOL><INDENT>y = np.array(y)<EOL><DEDENT>N = max(len(x), len(y))<EOL>if len(x) < N:<EOL><INDENT>x = y.copy()<EOL>x.resize(N)<EOL><DEDENT>if len(y) < N:<EOL><INDENT>y = y.copy()<EOL>y.resize(N)<EOL><DEDENT>if maxlags is None:<EOL><INDENT>maxlags = N - <NUM_LIT:1><EOL><DEDENT>assert maxlags < N, '<STR_LIT>'<EOL>realdata = np.isrealobj(x) and np.isrealobj(y)<EOL>if realdata == True:<EOL><INDENT>r = np.zeros(maxlags, dtype=float)<EOL><DEDENT>else:<EOL><INDENT>r = np.zeros(maxlags, dtype=complex)<EOL><DEDENT>if norm == '<STR_LIT>':<EOL><INDENT>rmsx = pylab_rms_flat(x)<EOL>rmsy = pylab_rms_flat(y)<EOL><DEDENT>for k in range(<NUM_LIT:0>, maxlags+<NUM_LIT:1>):<EOL><INDENT>nk = N - k - <NUM_LIT:1><EOL>if realdata == True:<EOL><INDENT>sum = <NUM_LIT:0><EOL>for j in range(<NUM_LIT:0>, nk+<NUM_LIT:1>):<EOL><INDENT>sum = sum + x[j+k] * y[j]<EOL><DEDENT><DEDENT>else:<EOL><INDENT>sum = <NUM_LIT:0.> + <NUM_LIT><EOL>for j in range(<NUM_LIT:0>, nk+<NUM_LIT:1>):<EOL><INDENT>sum = sum + x[j+k] * y[j].conjugate()<EOL><DEDENT><DEDENT>if k == <NUM_LIT:0>:<EOL><INDENT>if norm in ['<STR_LIT>', '<STR_LIT>']:<EOL><INDENT>r0 = sum/float(N)<EOL><DEDENT>elif norm is None:<EOL><INDENT>r0 = sum<EOL><DEDENT>else:<EOL><INDENT>r0 =  <NUM_LIT:1.><EOL><DEDENT><DEDENT>else:<EOL><INDENT>if norm == '<STR_LIT>':<EOL><INDENT>r[k-<NUM_LIT:1>] = sum / float(N-k)<EOL><DEDENT>elif norm == '<STR_LIT>':<EOL><INDENT>r[k-<NUM_LIT:1>] = sum / float(N)<EOL><DEDENT>elif norm is None:<EOL><INDENT>r[k-<NUM_LIT:1>] = sum<EOL><DEDENT>elif norm == '<STR_LIT>':<EOL><INDENT>r[k-<NUM_LIT:1>] =  sum/(rmsx*rmsy)/float(N)<EOL><DEDENT><DEDENT><DEDENT>r = np.insert(r, <NUM_LIT:0>, r0)<EOL>return r<EOL>

r"""Correlation function

    This function should give the same results as :func:`xcorr` but it
    returns the positive lags only. Moreover the algorithm does not use
    FFT as compared to other algorithms.

    :param array x: first data array of length N
    :param array y: second data array of length N. If not specified, computes the
        autocorrelation.
    :param int maxlags: compute cross correlation between [0:maxlags]
        when maxlags is not specified, the range of lags is [0:maxlags].
    :param str norm: normalisation in ['biased', 'unbiased', None, 'coeff']

        * *biased*   correlation=raw/N,
        * *unbiased* correlation=raw/(N-`|lag|`)
        * *coeff*    correlation=raw/(rms(x).rms(y))/N
        * None       correlation=raw

    :return:
        * a numpy.array correlation sequence,  r[1,N]
        * a float for the zero-lag correlation,  r[0]

    The *unbiased* correlation has the form:

    .. math::

        \hat{r}_{xx} = \frac{1}{N-m}T \sum_{n=0}^{N-m-1} x[n+m]x^*[n] T

    The *biased* correlation differs by the front factor only:

    .. math::

        \check{r}_{xx} = \frac{1}{N}T \sum_{n=0}^{N-m-1} x[n+m]x^*[n] T

    with :math:`0\leq m\leq N-1`.

    .. doctest::

        >>> from spectrum import CORRELATION
        >>> x = [1,2,3,4,5]
        >>> res = CORRELATION(x,x, maxlags=0, norm='biased')
        >>> res[0]
        11.0

    .. note:: this function should be replaced by :func:`xcorr`.

    .. seealso:: :func:`xcorr`


def xcorr(x, y=None, maxlags=None, norm='<STR_LIT>'):

N = len(x)<EOL>if y is None:<EOL><INDENT>y = x<EOL><DEDENT>assert len(x) == len(y), '<STR_LIT>'<EOL>if maxlags is None:<EOL><INDENT>maxlags = N-<NUM_LIT:1><EOL>lags = np.arange(<NUM_LIT:0>, <NUM_LIT:2>*N-<NUM_LIT:1>)<EOL><DEDENT>else:<EOL><INDENT>assert maxlags <= N, '<STR_LIT>'<EOL>lags = np.arange(N-maxlags-<NUM_LIT:1>, N+maxlags)<EOL><DEDENT>res = np.correlate(x, y, mode='<STR_LIT>')<EOL>if norm == '<STR_LIT>':<EOL><INDENT>Nf = float(N)<EOL>res = res[lags] / float(N)    <EOL><DEDENT>elif norm == '<STR_LIT>':<EOL><INDENT>res = res[lags] / (float(N)-abs(np.arange(-N+<NUM_LIT:1>, N)))[lags]<EOL><DEDENT>elif norm == '<STR_LIT>':<EOL><INDENT>Nf = float(N)<EOL>rms = pylab_rms_flat(x) * pylab_rms_flat(y)<EOL>res = res[lags] / rms / Nf<EOL><DEDENT>else:<EOL><INDENT>res = res[lags]<EOL><DEDENT>lags = np.arange(-maxlags, maxlags+<NUM_LIT:1>)<EOL>return res, lags<EOL>

Cross-correlation using numpy.correlate

    Estimates the cross-correlation (and autocorrelation) sequence of a random
    process of length N. By default, there is no normalisation and the output
    sequence of the cross-correlation has a length 2*N+1.

    :param array x: first data array of length N
    :param array y: second data array of length N. If not specified, computes the
        autocorrelation.
    :param int maxlags: compute cross correlation between [-maxlags:maxlags]
        when maxlags is not specified, the range of lags is [-N+1:N-1].
    :param str option: normalisation in ['biased', 'unbiased', None, 'coeff']

    The true cross-correlation sequence is

    .. math:: r_{xy}[m] = E(x[n+m].y^*[n]) = E(x[n].y^*[n-m])

    However, in practice, only a finite segment of one realization of the
    infinite-length random process is available.

    The correlation is estimated using numpy.correlate(x,y,'full').
    Normalisation is handled by this function using the following cases:

        * 'biased': Biased estimate of the cross-correlation function
        * 'unbiased': Unbiased estimate of the cross-correlation function
        * 'coeff': Normalizes the sequence so the autocorrelations at zero
           lag is 1.0.

    :return:
        * a numpy.array containing the cross-correlation sequence (length 2*N-1)
        * lags vector

    .. note:: If x and y are not the same length, the shorter vector is
        zero-padded to the length of the longer vector.

    .. rubric:: Examples

    .. doctest::

        >>> from spectrum import xcorr
        >>> x = [1,2,3,4,5]
        >>> c, l = xcorr(x,x, maxlags=0, norm='biased')
        >>> c
        array([ 11.])

    .. seealso:: :func:`CORRELATION`.


L = numpy.linalg.cholesky(A)<EOL>y = numpy.linalg.solve(L,B)<EOL>x = numpy.linalg.solve(L.transpose().conjugate(),y)<EOL>return x, L<EOL>

Solve Ax=B using numpy cholesky solver

    A = LU

    in the case where A is square and Hermitian, A = L.L* where L* is
    transpoed and conjugate matrix

    Ly = b

    where

    Ux=y

    so x = U^{-1} y
    where U = L*
    and y = L^{-1} B


x = numpy.linalg.solve(A, B)<EOL>return x<EOL>

This function solve Ax=B directly without taking care of the input
    matrix properties.


if method == '<STR_LIT>':<EOL><INDENT>X = _numpy_solver(A,B)<EOL>return X<EOL><DEDENT>elif method == '<STR_LIT>':<EOL><INDENT>X, _L = _numpy_cholesky(A, B)<EOL>return X<EOL><DEDENT>elif method == '<STR_LIT>':<EOL><INDENT>import scipy.linalg<EOL>L = scipy.linalg.cholesky(A)<EOL>X = scipy.linalg.cho_solve((L, False), B)<EOL><DEDENT>else:<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT>return X<EOL>

Solve linear system `AX=B` using CHOLESKY method.

    :param A: an input Hermitian matrix
    :param B: an array
    :param str method: a choice of method in [numpy, scipy, numpy_solver]

        * `numpy_solver` relies entirely on numpy.solver (no cholesky decomposition)
        * `numpy` relies on the numpy.linalg.cholesky for the decomposition and
          numpy.linalg.solve for the inversion.
        * `scipy` uses scipy.linalg.cholesky for the decomposition and
          scipy.linalg.cho_solve for the inversion.

    .. rubric:: Description

    When a matrix is square and Hermitian (symmetric with lower part being
    the complex conjugate of the upper one), then the usual triangular
    factorization takes on the special form:

    .. math:: A = R R^H

    where :math:`R` is a lower triangular matrix with nonzero real principal
    diagonal element. The input matrix can be made of complex data. Then, the
    inversion to find :math:`x` is made as follows:

    .. math::  Ry = B

    and

    .. math::   Rx = y

    .. doctest::

        >>> import numpy
        >>> from spectrum import CHOLESKY
        >>> A = numpy.array([[ 2.0+0.j ,  0.5-0.5j, -0.2+0.1j],
        ...    [ 0.5+0.5j,  1.0+0.j ,  0.3-0.2j],
        ...    [-0.2-0.1j,  0.3+0.2j,  0.5+0.j ]])
        >>> B = numpy.array([ 1.0+3.j ,  2.0-1.j ,  0.5+0.8j])
        >>> CHOLESKY(A, B)
        array([ 0.95945946+5.25675676j,  4.41891892-7.04054054j,
               -5.13513514+6.35135135j])


Pv = []<EOL>N = len(X)<EOL>A = np.zeros(N, dtype=complex)<EOL>D = np.zeros(N, dtype=complex)<EOL>C = np.zeros(N, dtype=complex)<EOL>R = np.zeros(N, dtype=complex)<EOL>R1=<NUM_LIT:0.><EOL>for K in range(<NUM_LIT:1>, N-<NUM_LIT:1>):<EOL><INDENT>R1=R1 + <NUM_LIT>*(X[K].real**<NUM_LIT:2> + X[K].imag**<NUM_LIT:2>)<EOL><DEDENT>R2 = X[<NUM_LIT:0>].real**<NUM_LIT:2> + X[<NUM_LIT:0>].imag**<NUM_LIT:2><EOL>R3 = X[N-<NUM_LIT:1>].real**<NUM_LIT:2> + X[N-<NUM_LIT:1>].imag**<NUM_LIT:2><EOL>R4 = <NUM_LIT:1.> / (R1 + <NUM_LIT> * (R2 + R3))<EOL>P = R1 + R2 + R3<EOL>DELTA = <NUM_LIT:1.> - R2 * R4<EOL>GAMMA = <NUM_LIT:1.> - R3 * R4<EOL>LAMBDA = (X[<NUM_LIT:0>] * X[N-<NUM_LIT:1>]).conjugate()*R4<EOL>C[<NUM_LIT:0>] = X[N-<NUM_LIT:1>] * R4<EOL>D[<NUM_LIT:0>] = X[<NUM_LIT:0>].conjugate() * R4<EOL>M = <NUM_LIT:0><EOL>if (IP ==<NUM_LIT:0>):<EOL><INDENT>P = (<NUM_LIT>*R1+R2+R3)/float(N)<EOL>return [], P, []<EOL><DEDENT>for M in range(<NUM_LIT:0>, IP):<EOL><INDENT>SAVE1 = <NUM_LIT:0>+<NUM_LIT><EOL>for K in range(M+<NUM_LIT:1>, N):<EOL><INDENT>SAVE1 = SAVE1 + X[K]*X[K-M-<NUM_LIT:1>].conjugate()<EOL><DEDENT>SAVE1 *= <NUM_LIT><EOL>R[M] = SAVE1.conjugate()<EOL>THETA = X[N-<NUM_LIT:1>]*D[<NUM_LIT:0>]<EOL>PSI=X[N-<NUM_LIT:1>]*C[<NUM_LIT:0>]<EOL>XI = X[<NUM_LIT:0>].conjugate() * D[<NUM_LIT:0>]<EOL>if M==<NUM_LIT:0>:<EOL><INDENT>pass<EOL><DEDENT>else:<EOL><INDENT>for K in range(<NUM_LIT:0>, M):<EOL><INDENT>THETA=THETA+X[N-K-<NUM_LIT:2>]*D[K+<NUM_LIT:1>]    <EOL>PSI = PSI + X[N-K-<NUM_LIT:2>]*C[K+<NUM_LIT:1>]    <EOL>XI = XI + X[K+<NUM_LIT:1>].conjugate() * D[K+<NUM_LIT:1>] <EOL>R[K] = R[K]-X[N-M-<NUM_LIT:1>] * X[N+<NUM_LIT:1>-M+K-<NUM_LIT:1>].conjugate() - X[M].conjugate() * X[M-K-<NUM_LIT:1>] <EOL>SAVE1=SAVE1+R[K].conjugate()*A[M-K-<NUM_LIT:1>]             <EOL><DEDENT><DEDENT>C1 = -SAVE1/P<EOL>A[M]=C1                                   <EOL>P=P*(<NUM_LIT:1.>-C1.real**<NUM_LIT:2>-C1.imag**<NUM_LIT:2>)            <EOL>if M==<NUM_LIT:0>:<EOL><INDENT>pass<EOL><DEDENT>else:<EOL><INDENT>for K in range(<NUM_LIT:0>, (M+<NUM_LIT:1>)//<NUM_LIT:2>):<EOL><INDENT>MK = M-K-<NUM_LIT:1><EOL>SAVE1=A[K]<EOL>A[K]=SAVE1+C1*A[MK].conjugate() <EOL>if (K != MK):<EOL><INDENT>A[MK]=A[MK]+C1*(SAVE1.conjugate()) <EOL><DEDENT><DEDENT><DEDENT>if M+<NUM_LIT:1> == IP:<EOL><INDENT>P=<NUM_LIT>*P/float(N-M-<NUM_LIT:1>)<EOL>Pv.append(P)<EOL>return A, P, Pv<EOL><DEDENT>else:<EOL><INDENT>Pv.append(<NUM_LIT>*P/float(N-M-<NUM_LIT:1>))<EOL><DEDENT>R1=<NUM_LIT:1.>/(DELTA*GAMMA-(LAMBDA.real)**<NUM_LIT:2>-(LAMBDA.imag)**<NUM_LIT:2>)<EOL>C1=(THETA*(LAMBDA.conjugate())+PSI*DELTA)*R1<EOL>C2=(PSI*LAMBDA+THETA*GAMMA)*R1<EOL>C3=(XI*(LAMBDA.conjugate())+THETA*DELTA)*R1<EOL>C4=(THETA*LAMBDA+XI*GAMMA)*R1<EOL>for K in range(<NUM_LIT:0>, (M)//<NUM_LIT:2>+<NUM_LIT:1>):<EOL><INDENT>MK=M-K<EOL>SAVE1=C[K].conjugate()<EOL>SAVE2=D[K].conjugate()<EOL>SAVE3=C[MK].conjugate()<EOL>SAVE4=D[MK].conjugate()<EOL>C[K]=C[K]+C1*SAVE3+C2*SAVE4                <EOL>D[K]=D[K]+C3*SAVE3+C4*SAVE4                <EOL>if K != MK:<EOL><INDENT>C[MK]=C[MK]+C1*SAVE1+C2*SAVE2              <EOL>D[MK]=D[MK]+C3*SAVE1+C4*SAVE2              <EOL><DEDENT><DEDENT>R2=PSI.real**<NUM_LIT:2>+PSI.imag**<NUM_LIT:2><EOL>R3=THETA.real**<NUM_LIT:2>+THETA.imag**<NUM_LIT:2><EOL>R4=XI.real**<NUM_LIT:2>+XI.imag**<NUM_LIT:2><EOL>R5=GAMMA-(R2*DELTA+R3*GAMMA+<NUM_LIT>*np.real(PSI*LAMBDA*THETA.conjugate()))*R1<EOL>R2=DELTA-(R3*DELTA+R4*GAMMA+<NUM_LIT>*np.real(THETA*LAMBDA*XI.conjugate()))*R1<EOL>GAMMA=R5                                     <EOL>DELTA=R2                                     <EOL>LAMBDA=LAMBDA+C3*PSI.conjugate()+C4*THETA.conjugate()  <EOL>if P <= <NUM_LIT:0.>:<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT>if (DELTA > <NUM_LIT:0.> and DELTA <= <NUM_LIT:1.> and GAMMA > <NUM_LIT:0.> and GAMMA <=<NUM_LIT:1.>):<EOL><INDENT>pass<EOL><DEDENT>else:<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT>R1=<NUM_LIT:1.>/P<EOL>R2=<NUM_LIT:1.>/(DELTA*GAMMA-LAMBDA.real**<NUM_LIT:2>-LAMBDA.imag**<NUM_LIT:2>) <EOL>EF=X[M+<NUM_LIT:1>]<EOL>EB=X[N-M-<NUM_LIT:2>]<EOL>for K in range(<NUM_LIT:0>, M+<NUM_LIT:1>):<EOL><INDENT>EF=EF+A[K]*X[M-K]                        <EOL>EB=EB+A[K].conjugate()*X[N-M+K-<NUM_LIT:1>]            <EOL><DEDENT>C1=EB*R1                                     <EOL>C2=EF.conjugate()*R1                              <EOL>C3=(EB.conjugate()*DELTA+EF*LAMBDA)*R2<EOL>C4=(EF*GAMMA+(EB*LAMBDA).conjugate())*R2<EOL>for K in range(M, -<NUM_LIT:1>, -<NUM_LIT:1>):<EOL><INDENT>SAVE1=A[K]<EOL>A[K]=SAVE1+C3*C[K]+C4*D[K]                 <EOL>C[K+<NUM_LIT:1>]=C[K]+C1*SAVE1                       <EOL>D[K+<NUM_LIT:1>]=D[K]+C2*SAVE1                       <EOL><DEDENT>C[<NUM_LIT:0>]=C1<EOL>D[<NUM_LIT:0>]=C2<EOL>R3=EB.real**<NUM_LIT:2>+EB.imag**<NUM_LIT:2><EOL>R4=EF.real**<NUM_LIT:2>+EF.imag**<NUM_LIT:2><EOL>P=P-(R3*DELTA+R4*GAMMA+<NUM_LIT>*np.real(EF*EB*LAMBDA))*R2  <EOL>DELTA=DELTA-R4*R1                            <EOL>GAMMA=GAMMA-R3*R1                            <EOL>LAMBDA=LAMBDA+(EF*EB).conjugate()*R1                <EOL>if (P > <NUM_LIT:0.>):<EOL><INDENT>pass<EOL><DEDENT>else:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>if (DELTA > <NUM_LIT:0.> and DELTA <= <NUM_LIT:1.> and  GAMMA > <NUM_LIT:0.> and GAMMA <= <NUM_LIT:1.>):<EOL><INDENT>pass<EOL><DEDENT>else:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT><DEDENT>

Fast algorithm for the solution of the modified covariance least squares normal equations.

    This implementation is based on [Marple]_. This code is far more
    complicated and slower than :func:`modcovar` function, which is now the official version.
    See :func:`modcovar` for a detailed description of Modified Covariance method.

    :param X:    - Array of complex data samples X(1) through X(N)
    :param int IP:   - Order of linear prediction model (integer)

    :return:
        * P    - Real linear prediction variance at order IP
        * A    - Array of complex linear prediction coefficients
        * ISTAT - Integer status indicator at time of exit
              0. for normal exit (no numerical ill-conditioning)
              1. if P is not a positive value
              2. if DELTA' and GAMMA' do not lie in the range 0 to 1
              3. if P' is not a positive value
              4. if DELTA and GAMMA do not lie in the range 0 to 1

    :validation: the AR parameters are the same as those returned by
        a completely different function :func:`modcovar`.

    .. note:: validation. results similar to test example in Marple but
        starts to differ for    ip~8. with ratio of 0.975 for ip=15 probably
        due to precision.

    :References: [Marple]_


from spectrum import corrmtx<EOL>import scipy.linalg<EOL>X = corrmtx(x, order, '<STR_LIT>')<EOL>Xc = np.matrix(X[:,<NUM_LIT:1>:])<EOL>X1 = np.array(X[:,<NUM_LIT:0>])<EOL>a, residues, rank, singular_values = scipy.linalg.lstsq(-Xc, X1)<EOL>Cz = np.dot(X1.conj().transpose(), Xc)<EOL>e = np.dot(X1.conj().transpose(), X1) + np.dot(Cz, a)<EOL>assert e.imag < <NUM_LIT>, '<STR_LIT>'<EOL>e = float(e.real) <EOL>return a, e<EOL>

Simple and fast implementation of the covariance AR estimate

    This code is 10 times faster than :func:`modcovar_marple` and more importantly
    only 10 lines of code, compared to a 200 loc for :func:`modcovar_marple`

    :param X:        Array of complex data samples
    :param int order:   Order of linear prediction model

    :return:
        * P    - Real linear prediction variance at order IP
        * A    - Array of complex linear prediction coefficients

    .. plot::
        :include-source:
        :width: 80%

        from spectrum import modcovar, marple_data, arma2psd, cshift
        from pylab import log10, linspace, axis, plot

        a, p = modcovar(marple_data, 15)
        PSD = arma2psd(a)
        PSD = cshift(PSD, len(PSD)/2) # switch positive and negative freq
        plot(linspace(-0.5, 0.5, 4096), 10*log10(PSD/max(PSD)))
        axis([-0.5,0.5,-60,0])

    .. seealso:: :class:`~spectrum.modcovar.pmodcovar`

    :validation: the AR parameters are the same as those returned by
        a completely different function :func:`modcovar_marple`.

    :References: Mathworks


def __init__(self, data, order, NFFT=None, sampling=<NUM_LIT:1.>,<EOL>scale_by_freq=False):

super(pmodcovar, self).__init__(data, ar_order=order,<EOL>NFFT=NFFT, sampling=sampling,<EOL>scale_by_freq=scale_by_freq)<EOL>

**Constructor**

        For a detailled description of the parameters, see :func:`modcovar`.

        :param array data: input data (list or numpy.array)
        :param int order:
        :param int NFFT: total length of the final data sets (padded with
            zero if needed; default is 4096)
        :param float sampling: sampling frequency of the input :attr:`data`.


if n <= <NUM_LIT:0>:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>x = numpy.linspace(lb, ub, n)<EOL>psi = numpy.cos(<NUM_LIT:5>*x) * numpy.exp(-x**<NUM_LIT:2>/<NUM_LIT>)<EOL>return psi<EOL>

r"""Generate the Morlet waveform

    The Morlet waveform is defined as follows:

    .. math:: w[x] = \cos{5x}  \exp^{-x^2/2}

    :param lb: lower bound
    :param ub: upper bound
    :param int n: waveform data samples

    .. plot::
        :include-source:
        :width: 80%

        from spectrum import morlet
        from pylab import plot
        plot(morlet(0,10,100))


def chirp(t, f0=<NUM_LIT:0.>, t1=<NUM_LIT:1.>, f1=<NUM_LIT>, form='<STR_LIT>', phase=<NUM_LIT:0>):

valid_forms = ['<STR_LIT>', '<STR_LIT>', '<STR_LIT>']<EOL>if form not in valid_forms:<EOL><INDENT>raise ValueError("<STR_LIT>"<EOL>% valid_forms)<EOL><DEDENT>t = numpy.array(t)<EOL>phase = <NUM_LIT> * pi * phase / <NUM_LIT><EOL>if form == "<STR_LIT>":<EOL><INDENT>a = pi * (f1 - f0)/t1<EOL>b = <NUM_LIT> * pi * f0<EOL>y = numpy.cos(a * t**<NUM_LIT:2> + b*t + phase)<EOL><DEDENT>elif form == "<STR_LIT>":<EOL><INDENT>a = (<NUM_LIT:2>/<NUM_LIT> * pi * (f1-f0)/t1/t1)<EOL>b = <NUM_LIT> * pi * f0<EOL>y = numpy.cos(a*t**<NUM_LIT:3> + b * t + phase)<EOL><DEDENT>elif form == "<STR_LIT>":<EOL><INDENT>a = <NUM_LIT> * pi * t1/numpy.log(f1-f0)<EOL>b = <NUM_LIT> * pi * f0<EOL>x = (f1-f0)**(<NUM_LIT:1.>/t1)<EOL>y = numpy.cos(a * x**t + b * t + phase)<EOL><DEDENT>return y<EOL>

r"""Evaluate a chirp signal at time t.

    A chirp signal is a frequency swept cosine wave.

    .. math:: a = \pi  (f_1 - f_0) / t_1
    .. math:: b = 2  \pi  f_0
    .. math:: y = \cos\left( \pi\frac{f_1-f_0}{t_1}  t^2 + 2\pi f_0 t + \rm{phase} \right)

    :param array t: times at which to evaluate the chirp signal
    :param float f0: frequency at time t=0 (Hz)
    :param float t1: time t1
    :param float f1: frequency at time t=t1 (Hz)
    :param str form: shape of frequency sweep in ['linear', 'quadratic', 'logarithmic']
    :param float phase: phase shift at t=0

    The parameter **form** can be:

        * 'linear'      :math:`f(t) = (f_1-f_0)(t/t_1) + f_0`
        * 'quadratic'   :math:`f(t) = (f_1-f_0)(t/t_1)^2 + f_0`
        * 'logarithmic' :math:`f(t) = (f_1-f_0)^{(t/t_1)} + f_0`

    Example:

    .. plot::
        :include-source:
        :width: 80%

        from spectrum import chirp
        from pylab import linspace, plot
        t = linspace(0, 1, 1000)
        y = chirp(t, form='linear')
        plot(y)
        y = chirp(t, form='quadratic')
        plot(y, 'r')


if n <= <NUM_LIT:0>:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>x = numpy.linspace(lb, ub, n)<EOL>psi = (<NUM_LIT:1.>-x**<NUM_LIT>) * (<NUM_LIT>/(numpy.sqrt(<NUM_LIT>)*pi**<NUM_LIT>)) * numpy.exp(-x**<NUM_LIT:2>/<NUM_LIT>)<EOL>return psi<EOL>

r"""Generate the mexican hat wavelet

    The Mexican wavelet is:

    .. math:: w[x] = \cos{5x}  \exp^{-x^2/2}

    :param lb: lower bound
    :param ub: upper bound
    :param int n: waveform data samples
    :return: the waveform

    .. plot::
        :include-source:
        :width: 80%

        from spectrum import mexican
        from pylab import plot
        plot(mexican(0, 10, 100))


return  <NUM_LIT>*x**<NUM_LIT:4>-<NUM_LIT>*x**<NUM_LIT:5>+<NUM_LIT>*x**<NUM_LIT:6>-<NUM_LIT>*x**<NUM_LIT:7><EOL>

r"""Compute the Meyer auxiliary function

    The Meyer function is

    .. math:: y = 35 x^4-84 x^5+70 x^6-20 x^7

    :param array x:
    :return: the waveform

    .. plot::
        :include-source:
        :width: 80%

        from spectrum import meyeraux
        from pylab import linspace, plot
        t = linspace(0, 1, 1000)
        plot(t, meyeraux(t))


from numpy import roots<EOL>assert len(b) == len(a), "<STR_LIT>"<EOL>g = b[<NUM_LIT:0>] / a[<NUM_LIT:0>]<EOL>z = roots(b)<EOL>p = roots(a)<EOL>return z, p, g<EOL>

Convert transfer function filter parameters to zero-pole-gain form

    Find the zeros, poles, and gains of this continuous-time system:

    .. warning:: b and a must have the same length.

    ::

        from spectrum import tf2zp
        b = [2,3,0]
        a = [1, 0.4, 1]
        [z,p,k] = tf2zp(b,a)          % Obtain zero-pole-gain form
        z =
            1.5
            0
        p =
           -0.2000 + 0.9798i
            -0.2000 - 0.9798i
        k =
           2

    :param b: numerator
    :param a: denominator
    :param fill: If True, check that the length of a and b are the same. If not, create a copy of the shortest element and append zeros to it.
    :return: z (zeros), p (poles), g (gain)

    Convert transfer function f(x)=sum(b*x^n)/sum(a*x^n) to
    zero-pole-gain form f(x)=g*prod(1-z*x)/prod(1-p*x)

    .. todo:: See if tf2ss followed by ss2zp gives better results.  These
        are available from the control system toolbox.  Note that
        the control systems toolbox doesn't bother, but instead uses

    .. seealso:: scipy.signal.tf2zpk, which gives the same results but uses a different
        algorithm (z^-1 instead of z).


d = abs(len(b)-len(a))<EOL>if d != <NUM_LIT:0>:<EOL><INDENT>if len(a) > len(b):<EOL><INDENT>try:<EOL><INDENT>b.extend([<NUM_LIT:0.>]*d)<EOL><DEDENT>except:<EOL><INDENT>b = np.append(b, [<NUM_LIT:0>]*d)<EOL><DEDENT><DEDENT>elif len(b)>len(a):<EOL><INDENT>try:<EOL><INDENT>a.extend([<NUM_LIT:0.>]*d)<EOL><DEDENT>except:<EOL><INDENT>a = np.append(a, [<NUM_LIT:0>]*d)<EOL><DEDENT><DEDENT>return b,a<EOL><DEDENT>else:<EOL><INDENT>return b,a<EOL><DEDENT>

Given two list or arrays, pad with zeros the shortest array

    :param b: list or array
    :param a: list or array

    .. doctest::

        >>> from spectrum.transfer import eqtflength
        >>> a = [1,2]
        >>> b = [1,2,3,4]
        >>> a, b, = eqtflength(a,b)


import scipy.signal<EOL>z,p,k = scipy.signal.tf2zpk(b, a)<EOL>return z,p,k<EOL>

Return zero, pole, gain (z,p,k) representation from a numerator,
    denominator representation of a linear filter.

    Convert zero-pole-gain filter parameters to transfer function form

    :param ndarray b:  numerator polynomial.
    :param ndarray a: numerator and denominator polynomials.

    :return:
        * z : ndarray        Zeros of the transfer function.
        * p : ndarray        Poles of the transfer function.
        * k : float        System gain.

    If some values of b are too close to 0, they are removed. In that case, a
    BadCoefficients warning is emitted.

    .. doctest::

        >>> import scipy.signal
        >>> from spectrum.transfer import tf2zpk
        >>> [b, a] = scipy.signal.butter(3.,.4)
        >>> z, p ,k = tf2zpk(b,a)

    .. seealso:: :func:`zpk2tf`
    .. note:: wrapper of scipy function tf2zpk


import scipy.signal<EOL>z, p, k = scipy.signal.ss2zpk(a, b, c, d, input=input)<EOL>return z, p, k<EOL>

State-space representation to zero-pole-gain representation.

    :param A: ndarray State-space representation of linear system.
    :param B: ndarray State-space representation of linear system.
    :param C: ndarray State-space representation of linear system.
    :param D: ndarray State-space representation of linear system.
    :param int input: optional For multiple-input systems, the input to use.

    :return:
        * z, p : sequence  Zeros and poles.
        * k : float System gain.

    .. note:: wrapper of scipy function ss2zpk


import scipy.signal<EOL>b, a = scipy.signal.zpk2tf(z, p, k)<EOL>return b, a<EOL>

r"""Return polynomial transfer function representation from zeros and poles

    :param ndarray z: Zeros of the transfer function.
    :param ndarray p: Poles of the transfer function.
    :param float k: System gain.

    :return:
        b : ndarray Numerator polynomial.
        a : ndarray Numerator and denominator polynomials.

    :func:`zpk2tf` forms transfer function polynomials from the zeros, poles, and gains
    of a system in factored form.

    zpk2tf(z,p,k) finds a rational transfer function

    .. math:: \frac{B(s)}{A(s)} = \frac{b_1 s^{n-1}+\dots b_{n-1}s+b_n}{a_1 s^{m-1}+\dots a_{m-1}s+a_m}

    given a system in factored transfer function form

    .. math:: H(s) = \frac{Z(s)}{P(s)} = k \frac{(s-z_1)(s-z_2)\dots(s-z_m)}{(s-p_1)(s-p_2)\dots(s-p_n)}

    with p being the pole locations, and z the zero locations, with as many.
    The gains for each numerator transfer function are in vector k.
    The zeros and poles must be real or come in complex conjugate pairs.
    The polynomial denominator coefficients are returned in row vector a and
    the polynomial numerator coefficients are returned in matrix b, which has
    as many rows as there are columns of z.

    Inf values can be used as place holders in z if some columns have fewer zeros than others.

    .. note:: wrapper of scipy function zpk2tf


import scipy.signal<EOL>return scipy.signal.zpk2ss(z,p,k)<EOL>

Zero-pole-gain representation to state-space representation

    :param sequence z,p: Zeros and poles.
    :param float k: System gain.

    :return:
        * A, B, C, D : ndarray State-space matrices.

    .. note:: wrapper of scipy function zpk2ss