dhermes · August 23, 2016 21:52
diff --git a/iam-usage.html b/iam-usage.html


 <!DOCTYPE html>
 <!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
 <!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
 <head>
  <meta charset="utf-8">

  <meta name="viewport" content="width=device-width, initial-scale=1.0">

  <title>IAM User Guide &mdash; gcloud 0.18.0 documentation</title>




    <link rel="shortcut icon" href="https://gcloud-python.readthedocs.io/en/latest/_static/favicon.ico"/>












    <link rel="stylesheet" href="https://gcloud-python.readthedocs.io/en/latest/_static/css/theme.css" type="text/css" />





    <link rel="top" title="gcloud 0.18.0 documentation" href="index.html"/>
        <link rel="next" title="Datastore Client" href="datastore-client.html"/>
        <link rel="prev" title="Authentication" href="gcloud-auth.html"/>


  <script src="https://gcloud-python.readthedocs.io/en/latest/_static/js/modernizr.min.js"></script>

 </head>

 <body class="wy-body-for-nav" role="document">

  <div class="wy-grid-for-nav">


    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search">



            <a href="index.html" class="icon icon-home"> gcloud



          </a>







 <div role="search">
  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
 </div>


        </div>

        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">



                <p class="caption"><span class="caption-text">gcloud</span></p>
 <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="gcloud-api.html">Shared Core Modules</a></li>
 <li class="toctree-l1"><a class="reference internal" href="gcloud-config.html">Configuration</a></li>
 <li class="toctree-l1"><a class="reference internal" href="gcloud-auth.html">Authentication</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">IAM User Guide</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="#iam-resources">IAM Resources</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="#members">Members</a></li>
 <li class="toctree-l3"><a class="reference internal" href="#roles">Roles</a></li>
 <li class="toctree-l3"><a class="reference internal" href="#policies">Policies</a></li>
 <li class="toctree-l3"><a class="reference internal" href="#policy-changes">Policy Changes</a></li>
 </ul>
 </li>
 <li class="toctree-l2"><a class="reference internal" href="#methods">Methods</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="#low-level-methods">Low Level Methods</a></li>
 <li class="toctree-l3"><a class="reference internal" href="#convenience-methods">Convenience Methods</a></li>
 </ul>
 </li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="#iam-for-contributors">IAM for Contributors</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Datastore</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="datastore-client.html">Client</a></li>
 <li class="toctree-l1"><a class="reference internal" href="datastore-entities.html">Entities</a></li>
 <li class="toctree-l1"><a class="reference internal" href="datastore-keys.html">Keys</a></li>
 <li class="toctree-l1"><a class="reference internal" href="datastore-queries.html">Queries</a></li>
 <li class="toctree-l1"><a class="reference internal" href="datastore-transactions.html">Transactions</a></li>
 <li class="toctree-l1"><a class="reference internal" href="datastore-batches.html">Batches</a></li>
 <li class="toctree-l1"><a class="reference internal" href="datastore-helpers.html">Helpers</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Storage</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="storage-client.html">Client</a></li>
 <li class="toctree-l1"><a class="reference internal" href="storage-blobs.html">Blobs / Objects</a></li>
 <li class="toctree-l1"><a class="reference internal" href="storage-buckets.html">Buckets</a></li>
 <li class="toctree-l1"><a class="reference internal" href="storage-acl.html">ACL</a></li>
 <li class="toctree-l1"><a class="reference internal" href="storage-batch.html">Batches</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Pub/Sub</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="pubsub-usage.html">Using the API</a></li>
 <li class="toctree-l1"><a class="reference internal" href="pubsub-client.html">Client</a></li>
 <li class="toctree-l1"><a class="reference internal" href="pubsub-topic.html">Topics</a></li>
 <li class="toctree-l1"><a class="reference internal" href="pubsub-subscription.html">Subscriptions</a></li>
 <li class="toctree-l1"><a class="reference internal" href="pubsub-message.html">Message</a></li>
 <li class="toctree-l1"><a class="reference internal" href="pubsub-iam.html">IAM Policy</a></li>
 </ul>
 <p class="caption"><span class="caption-text">BigQuery</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="bigquery-usage.html">Using the API</a></li>
 <li class="toctree-l1"><a class="reference internal" href="bigquery-client.html">Client</a></li>
 <li class="toctree-l1"><a class="reference internal" href="bigquery-dataset.html">Datasets</a></li>
 <li class="toctree-l1"><a class="reference internal" href="bigquery-job.html">Jobs</a></li>
 <li class="toctree-l1"><a class="reference internal" href="bigquery-table.html">Tables</a></li>
 <li class="toctree-l1"><a class="reference internal" href="bigquery-query.html">Query</a></li>
 <li class="toctree-l1"><a class="reference internal" href="bigquery-schema.html">Schemas</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Cloud Bigtable</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="bigtable-usage.html">Using the API</a></li>
 <li class="toctree-l1"><a class="reference internal" href="bigtable-client-intro.html">Base for Everything</a></li>
 <li class="toctree-l1"><a class="reference internal" href="bigtable-instance-api.html">Instance Admin API</a></li>
 <li class="toctree-l1"><a class="reference internal" href="bigtable-table-api.html">Table Admin API</a></li>
 <li class="toctree-l1"><a class="reference internal" href="bigtable-data-api.html">Data API</a></li>
 <li class="toctree-l1"><a class="reference internal" href="bigtable-client.html">Client</a></li>
 <li class="toctree-l1"><a class="reference internal" href="bigtable-instance.html">Instance</a></li>
 <li class="toctree-l1"><a class="reference internal" href="bigtable-cluster.html">Cluster</a></li>
 <li class="toctree-l1"><a class="reference internal" href="bigtable-table.html">Table</a></li>
 <li class="toctree-l1"><a class="reference internal" href="bigtable-column-family.html">Column Families</a></li>
 <li class="toctree-l1"><a class="reference internal" href="bigtable-row.html">Bigtable Row</a></li>
 <li class="toctree-l1"><a class="reference internal" href="bigtable-row-filters.html">Bigtable Row Filters</a></li>
 <li class="toctree-l1"><a class="reference internal" href="bigtable-row-data.html">Row Data</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Resource Manager</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="resource-manager-api.html">Overview</a></li>
 <li class="toctree-l1"><a class="reference internal" href="resource-manager-client.html">Client</a></li>
 <li class="toctree-l1"><a class="reference internal" href="resource-manager-project.html">Projects</a></li>
 </ul>
 <p class="caption"><span class="caption-text">DNS</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="dns-usage.html">Using the API</a></li>
 <li class="toctree-l1"><a class="reference internal" href="dns-client.html">Client</a></li>
 <li class="toctree-l1"><a class="reference internal" href="dns-zone.html">Managed Zones</a></li>
 <li class="toctree-l1"><a class="reference internal" href="dns-resource-record-set.html">Resource Record Sets</a></li>
 <li class="toctree-l1"><a class="reference internal" href="dns-changes.html">Change Sets</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Stackdriver Logging</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="logging-usage.html">Using the API</a></li>
 <li class="toctree-l1"><a class="reference internal" href="logging-usage.html#python-logging-handler-transports">Python logging handler transports</a></li>
 <li class="toctree-l1"><a class="reference internal" href="logging-client.html">Client</a></li>
 <li class="toctree-l1"><a class="reference internal" href="logging-logger.html">Logger</a></li>
 <li class="toctree-l1"><a class="reference internal" href="logging-entries.html">Entries</a></li>
 <li class="toctree-l1"><a class="reference internal" href="logging-metric.html">Metrics</a></li>
 <li class="toctree-l1"><a class="reference internal" href="logging-sink.html">Sinks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="logging-handlers.html">Python Logging Module Handler</a></li>
 <li class="toctree-l1"><a class="reference internal" href="logging-transports-sync.html">Python Logging Handler Sync Transport</a></li>
 <li class="toctree-l1"><a class="reference internal" href="logging-transports-thread.html">Python Logging Handler Threaded Transport</a></li>
 <li class="toctree-l1"><a class="reference internal" href="logging-transports-base.html">Python Logging Handler Sync Transport</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Stackdriver Error Reporting</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="error-reporting-usage.html">Using the API</a></li>
 <li class="toctree-l1"><a class="reference internal" href="error-reporting-client.html">Client</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Stackdriver Monitoring</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="monitoring-usage.html">Using the API</a></li>
 <li class="toctree-l1"><a class="reference internal" href="monitoring-client.html">Client</a></li>
 <li class="toctree-l1"><a class="reference internal" href="monitoring-metric.html">Metric Descriptors</a></li>
 <li class="toctree-l1"><a class="reference internal" href="monitoring-resource.html">Monitored Resource Descriptors</a></li>
 <li class="toctree-l1"><a class="reference internal" href="monitoring-group.html">Groups</a></li>
 <li class="toctree-l1"><a class="reference internal" href="monitoring-query.html">Time Series Query</a></li>
 <li class="toctree-l1"><a class="reference internal" href="monitoring-timeseries.html">Time Series</a></li>
 <li class="toctree-l1"><a class="reference internal" href="monitoring-label.html">Label Descriptors</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Translate</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="translate-usage.html">Using the API</a></li>
 <li class="toctree-l1"><a class="reference internal" href="translate-client.html">Client</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Vision</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="vision-usage.html">Using the Vision API</a></li>
 <li class="toctree-l1"><a class="reference internal" href="vision-client.html">Vision Client</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Natural Language</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="language-usage.html">Using the API</a></li>
 <li class="toctree-l1"><a class="reference internal" href="language-client.html">Client</a></li>
 <li class="toctree-l1"><a class="reference internal" href="language-document.html">Document</a></li>
 </ul>
 <p class="caption"><span class="caption-text">External Links</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference external" href="https://github.com/GoogleCloudPlatform/gcloud-python/">GitHub</a></li>
 <li class="toctree-l1"><a class="reference external" href="https://github.com/GoogleCloudPlatform/gcloud-python/issues">Issues</a></li>
 <li class="toctree-l1"><a class="reference external" href="http://stackoverflow.com/questions/tagged/gcloud-python">Stack Overflow</a></li>
 <li class="toctree-l1"><a class="reference external" href="https://pypi.python.org/pypi/gcloud">PyPI</a></li>
 </ul>



        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">


      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
        <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
        <a href="index.html">gcloud</a>
      </nav>



      <div class="wy-nav-content">
        <div class="rst-content">






 <div role="navigation" aria-label="breadcrumbs navigation">
  <ul class="wy-breadcrumbs">
    <li><a href="index.html">Docs</a> &raquo;</li>

    <li>IAM User Guide</li>
      <li class="wy-breadcrumbs-aside">


            <a href="_sources/iam-usage.txt" rel="nofollow"> View page source</a>


      </li>
  </ul>
  <hr/>
 </div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">

  <div class="section" id="iam-user-guide">
 <h1>IAM User Guide<a class="headerlink" href="#iam-user-guide" title="Permalink to this headline">#</a></h1>
 <div class="admonition note">
 <p class="first admonition-title">Note</p>
 <p class="last">This document assumes basic knowledge of Google Cloud IAM,
 see <a class="reference external" href="https://cloud.google.com/iam/docs/">the docs</a> for details</p>
 </div>
 <div class="section" id="iam-resources">
 <h2>IAM Resources<a class="headerlink" href="#iam-resources" title="Permalink to this headline">#</a></h2>
 <p>The <code class="docutils literal"><span class="pre">iam</span></code> module provides a number of resources necessary for interacting with IAM.</p>
 <div class="section" id="members">
 <h3>Members<a class="headerlink" href="#members" title="Permalink to this headline">#</a></h3>
 <p>An IAM member is one of the following:</p>
 <ul class="simple">
 <li><code class="docutils literal"><span class="pre">iam.user(email)</span></code> an individual Google account</li>
 <li><code class="docutils literal"><span class="pre">iam.service_account(email)</span></code> a Google Cloud Service Account</li>
 <li><code class="docutils literal"><span class="pre">iam.group(email)</span></code> a Google group.</li>
 <li><code class="docutils literal"><span class="pre">iam.domain(domain_name)</span></code> a Google apps domain</li>
 <li><code class="docutils literal"><span class="pre">iam.ALL_AUTHENTICATED_USERS</span></code> any authenticated Google user</li>
 <li><code class="docutils literal"><span class="pre">iam.ALL_USERS</span></code></li>
 </ul>
 <div class="admonition note">
 <p class="first admonition-title">Note</p>
 <p class="last">that all of these are convenience wrappers around strings.
 See the list of member string formats <a class="reference external" href="https://cloud.google.com/iam/docs/managing-policies">here</a>.</p>
 </div>
 </div>
 <div class="section" id="roles">
 <h3>Roles<a class="headerlink" href="#roles" title="Permalink to this headline">#</a></h3>
 <p>Roles represent bundles of permissions that can be added to members.  For a complete list of roles available on a resource run</p>
 <p><code class="docutils literal"><span class="pre">gcloud</span> <span class="pre">iam</span> <span class="pre">list-grantable-roles</span> <span class="pre">//fully/qualified/resource/path</span></code></p>
 <p>An <code class="docutils literal"><span class="pre">iam.Role</span></code> object has a name, title, and description</p>
 <ul class="simple">
 <li>An <code class="docutils literal"><span class="pre">iam.Role.name</span></code> is the canonical name of a role. This will be the value used as keys in policy dictionaries (see below), and will be referred to as the &#8220;role string&#8221; throughout this document. E.g. <code class="docutils literal"><span class="pre">'roles/owner'</span></code>.</li>
 <li><code class="docutils literal"><span class="pre">iam.Role.title</span></code> human readable title of the role. E.g. <code class="docutils literal"><span class="pre">'Owner'</span></code></li>
 <li><code class="docutils literal"><span class="pre">iam.Role.description</span></code> the description of a role</li>
 </ul>
 </div>
 <div class="section" id="policies">
 <h3>Policies<a class="headerlink" href="#policies" title="Permalink to this headline">#</a></h3>
 <p>A policy is a dictionary from role strings to sets of members. <code class="docutils literal"><span class="pre">resource.get_policy()</span></code> also provides etags and versions. An etag is used to provide optimistic concurrency controls on policy updates, while versions are provided for end-user versioning.</p>
 </div>
 <div class="section" id="policy-changes">
 <h3>Policy Changes<a class="headerlink" href="#policy-changes" title="Permalink to this headline">#</a></h3>
 <p>An <code class="docutils literal"><span class="pre">iam.PolicyChange</span></code> object encapsulates changes to made to a policy transactionally. The <code class="docutils literal"><span class="pre">iam.PolicyChange</span></code> constructor takes an optional <code class="docutils literal"><span class="pre">version</span></code> keyword argument, an integer to use as the policy version. If <code class="docutils literal"><span class="pre">version</span></code> is <code class="docutils literal"><span class="pre">None</span></code>, when applied <code class="docutils literal"><span class="pre">iam.PolicyChange</span></code> will increment whatever the current version of the policy is by 1.</p>
 <p>To apply a <code class="docutils literal"><span class="pre">iam.PolicyChange</span></code> to a resource which implements the IAM interface call the <code class="docutils literal"><span class="pre">apply()</span></code> method with the resource as an argument.</p>
 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">policy_change</span> <span class="o">=</span> <span class="n">iam</span><span class="o">.</span><span class="n">PolicyChange</span><span class="p">(</span><span class="n">version</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">iam</span><span class="o">.</span><span class="n">roles</span><span class="o">.</span><span class="n">OWNER</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="p">[</span><span class="n">iam</span><span class="o">.</span><span class="n">user</span><span class="p">(</span><span class="s1">&#39;alice@example.com&#39;</span><span class="p">)])</span>
 <span class="gp">&gt;&gt;&gt; </span><span class="n">policy</span><span class="p">,</span> <span class="n">version</span><span class="p">,</span> <span class="n">etag</span> <span class="o">=</span> <span class="n">policy_change</span><span class="o">.</span><span class="n">apply</span><span class="p">(</span><span class="n">resource</span><span class="p">)</span>
 <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">policy</span><span class="p">)</span>
 <span class="go">{&#39;roles/owner&#39;: set([&#39;user:alice@example.com&#39;])}</span>
 <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">version</span><span class="p">)</span>
 <span class="go">2</span>
 <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">etag</span><span class="p">)</span>
 <span class="go">xDSFbfdasfAEFdfCds</span>
 </pre></div>
 </div>
 <p>Apply returns the new policy, it&#8217;s version, and it&#8217;s etag.</p>
 <p>Optionally, a <code class="docutils literal"><span class="pre">version</span></code> keyword argument can be supplied to <code class="docutils literal"><span class="pre">apply</span></code> which will override the <code class="docutils literal"><span class="pre">version</span></code> behavior of the policy change.</p>
 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">_</span><span class="p">,</span> <span class="n">version</span><span class="p">,</span> <span class="n">_</span> <span class="o">=</span> <span class="n">policy_change</span><span class="o">.</span><span class="n">apply</span><span class="p">(</span><span class="n">resource</span><span class="p">,</span> <span class="n">version</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>
 <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">version</span><span class="p">)</span>
 <span class="go">3</span>
 </pre></div>
 </div>
 <p>Modifications can be added to a <code class="docutils literal"><span class="pre">iam.PolicyChange</span></code> object by one of two methods:</p>
 <p>First the user can directly add or remove members from a <code class="docutils literal"><span class="pre">Role</span></code>. <code class="docutils literal"><span class="pre">iam.PolicyChange</span></code> exposes two methods for this, <code class="docutils literal"><span class="pre">add</span></code> and <code class="docutils literal"><span class="pre">remove</span></code> which both take a role string or <code class="docutils literal"><span class="pre">iam.Role</span></code> object and a list of member strings.</p>
 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">policy_change</span> <span class="o">=</span> <span class="n">iam</span><span class="o">.</span><span class="n">PolicyChange</span><span class="p">()</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">iam</span><span class="o">.</span><span class="n">roles</span><span class="o">.</span><span class="n">OWNER</span><span class="p">,</span> <span class="p">[</span><span class="n">iam</span><span class="o">.</span><span class="n">user</span><span class="p">(</span><span class="s1">&#39;alice@example.com&#39;</span><span class="p">)])</span>
 <span class="gp">&gt;&gt;&gt; </span><span class="n">policy_change</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="n">iam</span><span class="o">.</span><span class="n">roles</span><span class="o">.</span><span class="n">EDITOR</span><span class="p">,</span> <span class="p">[</span><span class="n">iam</span><span class="o">.</span><span class="n">domain</span><span class="p">(</span><span class="s1">&#39;example.com&#39;</span><span class="p">),</span> <span class="n">iam</span><span class="o">.</span><span class="n">group</span><span class="p">(</span><span class="s1">&#39;devs@example.com&#39;</span><span class="p">)])</span>
 <span class="gp">&gt;&gt;&gt; </span><span class="n">policy</span><span class="p">,</span> <span class="n">_</span><span class="p">,</span> <span class="n">_</span> <span class="o">=</span> <span class="n">policy_change</span><span class="o">.</span><span class="n">apply</span><span class="p">(</span><span class="n">resource</span><span class="p">)</span>
 <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">iam</span><span class="o">.</span><span class="n">user</span><span class="p">(</span><span class="s1">&#39;alice@example.com&#39;</span><span class="p">)</span> <span class="ow">in</span> <span class="n">policy</span><span class="p">[</span><span class="n">iam</span><span class="o">.</span><span class="n">roles</span><span class="o">.</span><span class="n">OWNER</span><span class="o">.</span><span class="n">name</span><span class="p">])</span>
 <span class="go">True</span>
 <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">iam</span><span class="o">.</span><span class="n">domain</span><span class="p">(</span><span class="s1">&#39;example.com&#39;</span><span class="p">)</span> <span class="ow">in</span> <span class="n">policy</span><span class="p">[</span><span class="n">iam</span><span class="o">.</span><span class="n">roles</span><span class="o">.</span><span class="n">EDITOR</span><span class="o">.</span><span class="n">name</span><span class="p">])</span>
 <span class="go">False</span>
 </pre></div>
 </div>
 <p>Second the user can specify a &#8220;membership function&#8221; which will take a member string as an argument, and return <code class="docutils literal"><span class="pre">True</span></code> if the member should belong to the specified role, and <code class="docutils literal"><span class="pre">False</span></code> otherwise.</p>
 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">membership_fn</span><span class="p">(</span><span class="n">member</span><span class="p">):</span>
 <span class="gp">&gt;&gt;&gt; </span>    <span class="k">return</span> <span class="ow">not</span> <span class="n">iam</span><span class="o">.</span><span class="n">is_group</span><span class="p">(</span><span class="n">member</span><span class="p">)</span> <span class="ow">or</span> <span class="n">member</span> <span class="o">==</span> <span class="n">iam</span><span class="o">.</span><span class="n">user</span><span class="p">(</span><span class="s1">&#39;bob@example.com&#39;</span><span class="p">)</span>
 <span class="gp">&gt;&gt;&gt; </span><span class="n">policy_change</span><span class="o">.</span><span class="n">fn</span><span class="p">(</span><span class="n">iam</span><span class="o">.</span><span class="n">roles</span><span class="o">.</span><span class="n">READER</span><span class="p">,</span> <span class="n">membership_fn</span><span class="p">)</span>
 <span class="gp">&gt;&gt;&gt; </span><span class="n">policy</span><span class="p">,</span> <span class="n">_</span><span class="p">,</span> <span class="n">_</span> <span class="n">policy_change</span><span class="o">.</span><span class="n">apply</span><span class="p">(</span><span class="n">resource</span><span class="p">)</span>
 <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">([</span><span class="n">member</span> <span class="k">for</span> <span class="n">member</span> <span class="ow">in</span> <span class="n">policy</span><span class="p">[</span><span class="n">iam</span><span class="o">.</span><span class="n">roles</span><span class="o">.</span><span class="n">READER</span><span class="o">.</span><span class="n">name</span><span class="p">]</span> <span class="k">if</span> <span class="n">iam</span><span class="o">.</span><span class="n">is_group</span><span class="p">(</span><span class="n">member</span><span class="p">)])</span>
 <span class="go">[&#39;user:bob@example.com&#39;]</span>
 </pre></div>
 </div>
 </div>
 </div>
 <div class="section" id="methods">
 <h2>Methods<a class="headerlink" href="#methods" title="Permalink to this headline">#</a></h2>
 <p>Resources that implement the IAM interface provide the following methods:</p>
 <div class="section" id="low-level-methods">
 <h3>Low Level Methods<a class="headerlink" href="#low-level-methods" title="Permalink to this headline">#</a></h3>
 <p>Resources that implement IAM provide low level methods for interacting with IAM.</p>
 <p><code class="docutils literal"><span class="pre">get_policy</span></code> returns a tuple of <code class="docutils literal"><span class="pre">(policy,</span> <span class="pre">version,</span> <span class="pre">etag)</span></code> on the corresponding resource.</p>
 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">policy</span><span class="p">,</span> <span class="n">version</span><span class="p">,</span> <span class="n">etag</span> <span class="o">=</span> <span class="n">resource</span><span class="o">.</span><span class="n">get_policy</span><span class="p">()</span>
 <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">policy</span><span class="p">)</span>
 <span class="go">{</span>
 <span class="go">   &#39;roles/owner&#39;: set([&#39;user:alice@example.com&#39;]),</span>
 <span class="go">   &#39;roles/editor: set([&#39;group:admins@example.com&#39;]),</span>
 <span class="go">   &#39;roles/reader&#39;: set([&#39;domain:example.com&#39;, &#39;user:bob@example.com&#39;])</span>
 <span class="go">}</span>
 <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">version</span><span class="p">)</span>
 <span class="go">5</span>
 <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">etag</span><span class="p">)</span>
 <span class="go">ffdFADFdsgfsjrsHTY</span>
 </pre></div>
 </div>
 <p><code class="docutils literal"><span class="pre">set_policy</span></code> takes a policy dictionary, as well as optional <code class="docutils literal"><span class="pre">version</span></code> and <code class="docutils literal"><span class="pre">etag</span></code> paramters. If updates are made to your policy during this change, they will be overwritten with exactly what is in your policy, or, if an etag is specified they will fail with a <code class="docutils literal"><span class="pre">iam.ConcurrentModificationError</span></code>. <code class="docutils literal"><span class="pre">iam.PolicyChange</span></code> performs this &#8220;read-modify-write&#8221; cycle automatically for the user.</p>
 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">policy</span><span class="p">[</span><span class="s1">&#39;roles/owner&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s1">&#39;user:charles@example.com&#39;</span><span class="p">)</span>
 <span class="gp">&gt;&gt;&gt; </span><span class="n">policy</span><span class="p">,</span> <span class="n">version</span><span class="p">,</span> <span class="n">etag</span> <span class="o">=</span> <span class="n">resource</span><span class="o">.</span><span class="n">set_policy</span><span class="p">(</span><span class="n">policy</span><span class="p">,</span> <span class="n">etag</span><span class="o">=</span><span class="n">etag</span><span class="p">)</span>
 <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">version</span><span class="p">)</span>
 <span class="go">6</span>
 </pre></div>
 </div>
 <p><code class="docutils literal"><span class="pre">missing_permissions</span></code> takes an iterable of &#8220;permission strings&#8221; and returns those the user does not have on the resource</p>
 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">resource</span><span class="o">.</span><span class="n">missing_permissions</span><span class="p">(</span><span class="s1">&#39;resourcemanager.projects.get&#39;</span><span class="p">,</span> <span class="s1">&#39;resourcemanager.projects.delete&#39;</span><span class="p">)</span>
 <span class="go">set([&#39;resourcemanager.projects.get&#39;])</span>
 </pre></div>
 </div>
 <p>Returns permissions (if any), in the list that the user does not possess.</p>
 <p><code class="docutils literal"><span class="pre">query_grantable_roles()</span></code> returns a list of <code class="docutils literal"><span class="pre">iam.Role</span></code> objects that represent roles (and their associated metadata)
 which can be granted on the specified resource</p>
 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">resource</span><span class="o">.</span><span class="n">query_grantable_roles</span><span class="p">()</span>
 <span class="go">[&lt;Role&gt;, &lt;Role&gt;, &lt;Role&gt;]</span>
 </pre></div>
 </div>
 </div>
 <div class="section" id="convenience-methods">
 <h3>Convenience Methods<a class="headerlink" href="#convenience-methods" title="Permalink to this headline">#</a></h3>
 <p>The following methods are wrappers around the creation and application of an <code class="docutils literal"><span class="pre">iam.PolicyChange</span></code> object.</p>
 <p><code class="docutils literal"><span class="pre">add_role</span></code> takes a single member, and a single <code class="docutils literal"><span class="pre">iam.Role</span></code>, or role string, and adds the member to the role. <code class="docutils literal"><span class="pre">add_role</span></code></p>
 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">resource</span><span class="o">.</span><span class="n">add_role</span><span class="p">(</span><span class="n">iam</span><span class="o">.</span><span class="n">user</span><span class="p">(</span><span class="s1">&#39;alice@example.com&#39;</span><span class="p">),</span> <span class="n">iam</span><span class="o">.</span><span class="n">roles</span><span class="o">.</span><span class="n">OWNER</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
 </pre></div>
 </div>
 <p><code class="docutils literal"><span class="pre">remove_role</span></code> has the same signature as <code class="docutils literal"><span class="pre">add_role</span></code> but removes the member from the role.</p>
 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">resource</span><span class="o">.</span><span class="n">remove_role</span><span class="p">(</span><span class="n">iam</span><span class="o">.</span><span class="n">user</span><span class="p">(</span><span class="s1">&#39;bob@example.com&#39;</span><span class="p">),</span> <span class="n">iam</span><span class="o">.</span><span class="n">roles</span><span class="o">.</span><span class="n">OWNER</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
 </pre></div>
 </div>
 <p><code class="docutils literal"><span class="pre">add_roles</span></code> takes a single member, and an iterable of <code class="docutils literal"><span class="pre">iam.Role</span></code> s or role strings, and the member to each role</p>
 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">resource</span><span class="o">.</span><span class="n">add_roles</span><span class="p">(</span><span class="n">iam</span><span class="o">.</span><span class="n">user</span><span class="p">(</span><span class="s1">&#39;alice@example.com&#39;</span><span class="p">),</span> <span class="p">[</span><span class="n">iam</span><span class="o">.</span><span class="n">roles</span><span class="o">.</span><span class="n">OWNER</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="n">iam</span><span class="o">.</span><span class="n">roles</span><span class="o">.</span><span class="n">EDITOR</span><span class="o">.</span><span class="n">name</span><span class="p">])</span>
 </pre></div>
 </div>
 <p><code class="docutils literal"><span class="pre">remove_roles</span></code> has the same signature as <code class="docutils literal"><span class="pre">resource.add_roles</span></code> but removes all the specified roles from the member (where present)</p>
 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">resource</span><span class="o">.</span><span class="n">remove_roles</span><span class="p">(</span><span class="n">iam</span><span class="o">.</span><span class="n">group</span><span class="p">(</span><span class="s1">&#39;devs@example.com&#39;</span><span class="p">),</span> <span class="p">[</span><span class="n">iam</span><span class="o">.</span><span class="n">roles</span><span class="o">.</span><span class="n">OWNER</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="n">iam</span><span class="o">.</span><span class="n">roles</span><span class="o">.</span><span class="n">EDITOR</span><span class="o">.</span><span class="n">name</span><span class="p">])</span>
 </pre></div>
 </div>
 <p><code class="docutils literal"><span class="pre">add_members</span></code> takes an <code class="docutils literal"><span class="pre">iam.Role</span></code> and an iterable of members and adds each member to the role</p>
 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">resource</span><span class="o">.</span><span class="n">add_members</span><span class="p">(</span><span class="n">iam</span><span class="o">.</span><span class="n">roles</span><span class="o">.</span><span class="n">OWNER</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="p">[</span><span class="n">iam</span><span class="o">.</span><span class="n">domain</span><span class="p">(</span><span class="s1">&#39;example.com&#39;</span><span class="p">),</span> <span class="n">iam</span><span class="o">.</span><span class="n">service_account</span><span class="p">(</span><span class="s1">&#39;compute@iam.my-project.example.com&#39;</span><span class="p">)])</span>
 </pre></div>
 </div>
 <p><code class="docutils literal"><span class="pre">remove_members</span></code> has the same signature as <code class="docutils literal"><span class="pre">add_members</span></code> but removes all the members from the specified role.</p>
 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">resource</span><span class="o">.</span><span class="n">remove_members</span><span class="p">(</span><span class="n">iam</span><span class="o">.</span><span class="n">roles</span><span class="o">.</span><span class="n">OWNER</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="p">[</span><span class="n">iam</span><span class="o">.</span><span class="n">ALL_USERS</span><span class="p">])</span>
 </pre></div>
 </div>
 </div>
 </div>
 </div>
 <div class="section" id="iam-for-contributors">
 <h1>IAM for Contributors<a class="headerlink" href="#iam-for-contributors" title="Permalink to this headline">#</a></h1>
 <p>To add support for IAM to your resource, the following conditions must be met:</p>
 <ul class="simple">
 <li>The class must represent a resource that implements the IAM META API</li>
 <li>The object must provide a <code class="docutils literal"><span class="pre">path</span></code> property (a string that describes the canonical resource path)</li>
 <li>The object must provide a <code class="docutils literal"><span class="pre">self._client</span></code> member: An authenticated <code class="docutils literal"><span class="pre">Client</span></code> object</li>
 </ul>
 <p>If all of these conditions are met, then IAM support can be added to your class by simply inheriting from the mixin</p>
 <p><code class="docutils literal"><span class="pre">class</span> <span class="pre">MyResource(iam._IAMMixin):</span></code></p>
 </div>


           </div>
          </div>
          <footer>

    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">

        <a href="datastore-client.html" class="btn btn-neutral float-right" title="Datastore Client" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>


        <a href="gcloud-auth.html" class="btn btn-neutral" title="Authentication" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>

    </div>


  <hr/>

  <div role="contentinfo">
    <p>
        &copy; Copyright 2014, Google.

    </p>
  </div>
  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.

 </footer>

        </div>
      </div>

    </section>

  </div>





    <script type="text/javascript">
        var DOCUMENTATION_OPTIONS = {
            URL_ROOT:'./',
            VERSION:'0.18.0',
            COLLAPSE_INDEX:false,
            FILE_SUFFIX:'.html',
            HAS_SOURCE:  true
        };
    </script>
      <script type="text/javascript" src="https://gcloud-python.readthedocs.io/en/latest/_static/jquery.js"></script>
      <script type="text/javascript" src="https://gcloud-python.readthedocs.io/en/latest/_static/underscore.js"></script>
      <script type="text/javascript" src="https://gcloud-python.readthedocs.io/en/latest/_static/doctools.js"></script>





    <script type="text/javascript" src="https://gcloud-python.readthedocs.io/en/latest/_static/js/theme.js"></script>




  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.StickyNav.enable();
      });
  </script>


 </body>
 </html>