0.x/reference/derivepassphrase._internals.cli_helpers/index.html (77afddf) - derivepassphrase.git

index.html

<!doctype html>
<html lang="en" class="no-js">
  <head>
    
      <meta charset="utf-8">
      <meta name="viewport" content="width=device-width,initial-scale=1">
      
        <meta name="description" content="An almost faithful Python reimplementation of James Coglan's vault.">
      
      
        <meta name="author" content="Marco Ricci">
      
      
        <link rel="canonical" href="https://the13thletter.info/derivepassphrase/0.x/reference/derivepassphrase._internals.cli_helpers/">
      
      
      
      
      <link rel="icon" href="../../assets/images/favicon.png">
      <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.6.14">
    
    
      
        <title>Derivepassphrase. internals.cli helpers - derivepassphrase</title>
      
    
    
      <link rel="stylesheet" href="../../assets/stylesheets/main.342714a4.min.css">

</a>
    </li>

<li class="md-tabs__item">
        <a href="../../tutorials/" class="md-tabs__link">
          
  
  
    
  
  Tutorials & Examples

</a>
      </li>

<li class="md-tabs__item">
        <a href="../../how-tos/" class="md-tabs__link">
          
  
  
    
  
  How-Tos

</a>
      </li>

<li class="md-tabs__item">
        <a href="../" class="md-tabs__link">
          
  
  
    
  
  Reference

</a>
      </li>

<li class="md-tabs__item">
        <a href="../../explanation/" class="md-tabs__link">
          
  
  
    
  
  Design & Background

</a>
      </li>

<li class="md-tabs__item">
        <a href="../../changelog/" class="md-tabs__link">
          
  
  
    
  
  Changelog

</a>
      </li>

<li class="md-tabs__item">
        <a href="../../wishlist/" class="md-tabs__link">
          
  
  
    
  
  Wishlist

</a>
      </li>

</ul>
  </div>
</nav>
          
        
      
      <main class="md-main" data-md-component="main">
        <div class="md-main__inner md-grid">
          
            
              
              <div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
                <div class="md-sidebar__scrollwrap">
                  <div class="md-sidebar__inner">

</a>
    derivepassphrase
  </label>
  
    <div class="md-nav__source">
      <a href="https://github.com/the-13th-letter/derivepassphrase" title="Go to repository" class="md-source" data-md-component="source">
  <div class="md-source__icon md-icon">
    
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><path d="M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81"/></svg>
  </div>
  <div class="md-source__repository">
    the-13th-letter/derivepassphrase
  </div>
</a>
    </div>
  
  <ul class="md-nav__list" data-md-scrollfix>
    
      
      
  
  
  
  
    <li class="md-nav__item">
      <a href="../.." class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    Overview
    
  </span>

</a>
    </li>

<li class="md-nav__item md-nav__item--nested">
      
        
        
        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2" >
        
          
          <div class="md-nav__link md-nav__container">
            <a href="../../tutorials/" class="md-nav__link ">
              
  
  
  <span class="md-ellipsis">
    Tutorials & Examples
    
  </span>

</a>
            
              
              <label class="md-nav__link " for="__nav_2" id="__nav_2_label" tabindex="0">
                <span class="md-nav__icon md-icon"></span>
              </label>
            
          </div>
        
        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_2_label" aria-expanded="false">
          <label class="md-nav__title" for="__nav_2">
            <span class="md-nav__icon md-icon"></span>
            Tutorials & Examples
          </label>
          <ul class="md-nav__list" data-md-scrollfix>
            
              
            
              
                
  
  
  
  
    <li class="md-nav__item">
      <a href="../../tutorials/basic-setup-passphrase/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    Setting up derivepassphrase vault for three accounts, with a master passphrase
    
  </span>

</a>
    </li>

</ul>
        </nav>
      
    </li>

</a>
            
              
              <label class="md-nav__link " for="__nav_3" id="__nav_3_label" tabindex="0">
                <span class="md-nav__icon md-icon"></span>
              </label>
            
          </div>
        
        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="false">
          <label class="md-nav__title" for="__nav_3">
            <span class="md-nav__icon md-icon"></span>
            How-Tos
          </label>
          <ul class="md-nav__list" data-md-scrollfix>
            
              
            
              
                
  
  
  
  
    <li class="md-nav__item">
      <a href="../../how-tos/ssh-key/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    How to set up derivepassphrase vault with an SSH key
    
  </span>

</a>
    </li>

</ul>
        </nav>
      
    </li>

<li class="md-nav__item md-nav__item--nested">
      
        
        
        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4" >
        
          
          <div class="md-nav__link md-nav__container">
            <a href="../" class="md-nav__link ">
              
  
  
  <span class="md-ellipsis">
    Reference
    
  </span>

</a>
            
              
              <label class="md-nav__link " for="__nav_4" id="__nav_4_label" tabindex="0">
                <span class="md-nav__icon md-icon"></span>
              </label>
            
          </div>
        
        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="false">
          <label class="md-nav__title" for="__nav_4">
            <span class="md-nav__icon md-icon"></span>
            Reference
          </label>
          <ul class="md-nav__list" data-md-scrollfix>
            
              
            
              
                
  
  
  
  
    
    
      
        
      
        
      
        
      
        
      
    
    
    
      
      
        
      
    
    
    <li class="md-nav__item md-nav__item--nested">
      
        
        
        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4_2" >
        
          
          <label class="md-nav__link" for="__nav_4_2" id="__nav_4_2_label" tabindex="0">
            
  
  
  <span class="md-ellipsis">
    Man pages
    
  </span>

<span class="md-nav__icon md-icon"></span>
          </label>
        
        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_4_2_label" aria-expanded="false">
          <label class="md-nav__title" for="__nav_4_2">
            <span class="md-nav__icon md-icon"></span>
            Man pages
          </label>
          <ul class="md-nav__list" data-md-scrollfix>
            
              
                
  
  
  
  
    <li class="md-nav__item">
      <a href="../derivepassphrase.1/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    derivepassphrase(1)
    
  </span>

</a>
    </li>

<li class="md-nav__item">
      <a href="../derivepassphrase-vault.1/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    derivepassphrase-vault(1)
    
  </span>

</a>
    </li>

<li class="md-nav__item">
      <a href="../derivepassphrase-export.1/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    derivepassphrase-export(1)
    
  </span>

</a>
    </li>

<li class="md-nav__item">
      <a href="../derivepassphrase-export-vault.1/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    derivepassphrase-export-vault(1)
    
  </span>

</a>
    </li>

</ul>
        </nav>
      
    </li>

<li class="md-nav__item md-nav__item--nested">
      
        
        
        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4_3" >
        
          
          <label class="md-nav__link" for="__nav_4_3" id="__nav_4_3_label" tabindex="0">
            
  
  
  <span class="md-ellipsis">
    API docs: Module derivepassphrase
    
  </span>

<span class="md-nav__icon md-icon"></span>
          </label>
        
        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_4_3_label" aria-expanded="false">
          <label class="md-nav__title" for="__nav_4_3">
            <span class="md-nav__icon md-icon"></span>
            API docs: Module derivepassphrase
          </label>
          <ul class="md-nav__list" data-md-scrollfix>
            
              
                
  
  
  
  
    <li class="md-nav__item">
      <a href="../derivepassphrase.cli/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    Submodule cli
    
  </span>

</a>
    </li>

<li class="md-nav__item">
      <a href="../derivepassphrase.exporter/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    Subpackage exporter
    
  </span>

</a>
    </li>

<li class="md-nav__item">
      <a href="../derivepassphrase.sequin/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    Submodule sequin
    
  </span>

</a>
    </li>

<li class="md-nav__item">
      <a href="../derivepassphrase.ssh_agent/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    Submodule ssh_agent
    
  </span>

</a>
    </li>

<li class="md-nav__item">
      <a href="../derivepassphrase._types/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    Submodule _types
    
  </span>

</a>
    </li>

<li class="md-nav__item">
      <a href="../derivepassphrase.vault/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    Submodule vault
    
  </span>

</a>
    </li>

</ul>
        </nav>
      
    </li>

<li class="md-nav__item md-nav__item--nested">
      
        
        
        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4_4" >
        
          
          <label class="md-nav__link" for="__nav_4_4" id="__nav_4_4_label" tabindex="0">
            
  
  
  <span class="md-ellipsis">
    Technical prerequisites
    
  </span>

<span class="md-nav__icon md-icon"></span>
          </label>
        
        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_4_4_label" aria-expanded="false">
          <label class="md-nav__title" for="__nav_4_4">
            <span class="md-nav__icon md-icon"></span>
            Technical prerequisites
          </label>
          <ul class="md-nav__list" data-md-scrollfix>
            
              
                
  
  
  
  
    <li class="md-nav__item">
      <a href="../prerequisites-ssh-key/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    Using derivepassphrase vault with an SSH key
    
  </span>

</a>
    </li>

</ul>
        </nav>
      
    </li>

<li class="md-nav__item md-nav__item--nested">
      
        
        
        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5" >
        
          
          <div class="md-nav__link md-nav__container">
            <a href="../../explanation/" class="md-nav__link ">
              
  
  
  <span class="md-ellipsis">
    Design & Background
    
  </span>

</a>
            
              
              <label class="md-nav__link " for="__nav_5" id="__nav_5_label" tabindex="0">
                <span class="md-nav__icon md-icon"></span>
              </label>
            
          </div>
        
        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_5_label" aria-expanded="false">
          <label class="md-nav__title" for="__nav_5">
            <span class="md-nav__icon md-icon"></span>
            Design & Background
          </label>
          <ul class="md-nav__list" data-md-scrollfix>
            
              
            
              
                
  
  
  
  
    <li class="md-nav__item">
      <a href="../../explanation/faq-altered-versions/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    "altered versions" license requirement
    
  </span>

</a>
    </li>

<li class="md-nav__item">
      <a href="../../explanation/faq-vault-interchangable-passphrases/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    "interchangable passphrases" in vault
    
  </span>

</a>
    </li>

</ul>
        </nav>
      
    </li>

<li class="md-nav__item md-nav__item--nested">
      
        
        
        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_6" >
        
          
          <label class="md-nav__link" for="__nav_6" id="__nav_6_label" tabindex="0">
            
  
  
  <span class="md-ellipsis">
    Changelog
    
  </span>

<span class="md-nav__icon md-icon"></span>
          </label>
        
        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_6_label" aria-expanded="false">
          <label class="md-nav__title" for="__nav_6">
            <span class="md-nav__icon md-icon"></span>
            Changelog
          </label>
          <ul class="md-nav__list" data-md-scrollfix>
            
              
                
  
  
  
  
    <li class="md-nav__item">
      <a href="../../changelog/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    Changelog
    
  </span>

</a>
    </li>

<li class="md-nav__item">
      <a href="../../upgrade-notes/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    Upgrade notes
    
  </span>

</a>
    </li>

<li class="md-nav__item">
      <a href="../../pycompatibility/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    Python compatibility
    
  </span>

</a>
    </li>

</ul>
        </nav>
      
    </li>

<li class="md-nav__item md-nav__item--nested">
      
        
        
        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_7" >
        
          
          <div class="md-nav__link md-nav__container">
            <a href="../../wishlist/" class="md-nav__link ">
              
  
  
  <span class="md-ellipsis">
    Wishlist
    
  </span>

</a>
            
          </div>
        
        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_7_label" aria-expanded="false">
          <label class="md-nav__title" for="__nav_7">
            <span class="md-nav__icon md-icon"></span>
            Wishlist
          </label>
          <ul class="md-nav__list" data-md-scrollfix>
            
              
            
          </ul>
        </nav>
      
    </li>

</ul>
</nav>
                  </div>
                </div>
              </div>
            
            
              
              <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
                <div class="md-sidebar__scrollwrap">
                  <div class="md-sidebar__inner">

<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
  
  
  
    
  
  
    <label class="md-nav__title" for="__toc">
      <span class="md-nav__icon md-icon"></span>
      Table of contents
    </label>
    <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
      
        <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.LOCK_SIZE" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;LOCK_SIZE
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.ConfigurationMutex" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;ConfigurationMutex
    </span>
  </a>
  
    <nav class="md-nav" aria-label=" ConfigurationMutex">
      <ul class="md-nav__list">
        
          <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.ConfigurationMutex.lock" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;lock
    </span>
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.ConfigurationMutex.unlock" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;unlock
    </span>
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.ConfigurationMutex.write_lock_fileobj" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;write_lock_fileobj
    </span>
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.ConfigurationMutex.write_lock_file" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;write_lock_file
    </span>
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.ConfigurationMutex.write_lock_condition" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;write_lock_condition
    </span>
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.ConfigurationMutex.__enter__" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-method"></code>&nbsp;__enter__
    </span>
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.ConfigurationMutex.__exit__" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-method"></code>&nbsp;__exit__
    </span>
  </a>
  
</li>
        
      </ul>
    </nav>
  
</li>
      
        <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.ORIGIN" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;ORIGIN
    </span>
  </a>
  
    <nav class="md-nav" aria-label=" ORIGIN">
      <ul class="md-nav__list">
        
          <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.ORIGIN.INTERACTIVE" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;INTERACTIVE
    </span>
  </a>
  
</li>
        
      </ul>
    </nav>
  
</li>
      
        <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.shell_complete_path" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;shell_complete_path
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.is_completable_item" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;is_completable_item
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.shell_complete_service" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;shell_complete_service
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.configuration_mutex" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;configuration_mutex
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.get_tempdir" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;get_tempdir
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.config_filename" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;config_filename
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.load_config" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;load_config
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.migrate_and_load_old_config" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;migrate_and_load_old_config
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.save_config" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;save_config
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.load_user_config" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;load_user_config
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.get_suitable_ssh_keys" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;get_suitable_ssh_keys
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.prompt_for_selection" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;prompt_for_selection
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.select_ssh_key" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;select_ssh_key
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.prompt_for_passphrase" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;prompt_for_passphrase
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.toml_key" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;toml_key
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.check_for_misleading_passphrase" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;check_for_misleading_passphrase
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.default_error_callback" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;default_error_callback
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.key_to_phrase" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;key_to_phrase
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#derivepassphrase._internals.cli_helpers.print_config_as_sh_script" class="md-nav__link">
    <span class="md-ellipsis">
      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;print_config_as_sh_script
    </span>
  </a>
  
</li>
      
    </ul>
  
</nav>
                  </div>
                </div>
              </div>
            
          
          
            <div class="md-content" data-md-component="content">
              <article class="md-content__inner md-typeset">

<h1 id="derivepassphrase._internals.cli_helpers" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-module"></code>            <span class="doc doc-object-name doc-module-name">derivepassphrase._internals.cli_helpers</span>

<p>Helper functions for the derivepassphrase command-line.</p>

<details class="warning" open>
  <summary>Warning</summary>
  <p>Non-public module (implementation detail), provided for didactical and
educational purposes only. Subject to change without notice, including
removal.</p>
</details>

<span class="doc doc-labels">
      <small class="doc doc-label doc-label-module-attribute"><code>module-attribute</code></small>
  </span>

<p>The size of the record to lock at the beginning of the file, for locking
implementations that lock byte ranges instead of whole files.</p>
<p>While POSIX specifies that <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/fcntl.html#module-fcntl"><code>fcntl</code></a> locks shall support a size of zero to
denote &ldquo;any conceivable file size&rdquo;, the locking system available in
<a class="autorefs autorefs-external" href="https://docs.python.org/3/library/msvcrt.html#module-msvcrt"><code>msvcrt</code></a> does not support this, and requires an explicit size.</p>

</div>

<h2 id="derivepassphrase._internals.cli_helpers.ConfigurationMutex" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code>            <span class="doc doc-object-name doc-class-name">ConfigurationMutex</span>

<a href="#derivepassphrase._internals.cli_helpers.ConfigurationMutex" class="headerlink" title="Permanent link">&para;</a></h2>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">ConfigurationMutex</span><span class="p">()</span>
</code></pre></div>

<p>A mutual exclusion context manager for configuration edits.</p>
<p>See <a class="autorefs autorefs-internal" title="            configuration_mutex" href="#derivepassphrase._internals.cli_helpers.configuration_mutex"><code>configuration_mutex</code></a>.</p>

<span class="doc doc-labels">
      <small class="doc doc-label doc-label-instance-attribute"><code>instance-attribute</code></small>
  </span>

<a href="#derivepassphrase._internals.cli_helpers.ConfigurationMutex.lock" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><span class="n">lock</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="typing.Callable" href="https://docs.python.org/3/library/typing.html#typing.Callable">Callable</a></span><span class="p">[[],</span> <span class="kc">None</span><span class="p">]</span> <span class="o">=</span> <span class="n"><span title="derivepassphrase._internals.cli_helpers.ConfigurationMutex.__init__.lock_func">lock_func</span></span>
</code></pre></div>

<p>A function to lock the mutex exclusively.</p>
<p>This implementation uses a file descriptor of a well-known file,
which is opened before locking and closed after unlocking (and on
error when locking). On Windows, we use <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/msvcrt.html#msvcrt.locking"><code>msvcrt.locking</code></a>, on
other systems, we use <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/fcntl.html#fcntl.flock"><code>fcntl.flock</code></a>.</p>

<details class="note" open>
  <summary>Note</summary>
  <p>This is a normal Python function, not a method.</p>
</details>

<details class="warning" open>
  <summary>Warning</summary>
  <p>You really should not have to change this. <em>If you absolutely
must</em>, then it is <em>your responsibility</em> to ensure that
<a class="autorefs autorefs-internal" title="            lock

instance-attribute
  " href="#derivepassphrase._internals.cli_helpers.ConfigurationMutex.lock"><code>lock</code></a> and <a class="autorefs autorefs-internal" title="            unlock

instance-attribute
  " href="#derivepassphrase._internals.cli_helpers.ConfigurationMutex.unlock"><code>unlock</code></a> are still compatible.</p>
</details>
    </div>

</div>

<h3 id="derivepassphrase._internals.cli_helpers.ConfigurationMutex.unlock" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-attribute"></code>            <span class="doc doc-object-name doc-attribute-name">unlock</span>

<span class="doc doc-labels">
      <small class="doc doc-label doc-label-instance-attribute"><code>instance-attribute</code></small>
  </span>

<a href="#derivepassphrase._internals.cli_helpers.ConfigurationMutex.unlock" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><span class="n">unlock</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="typing.Callable" href="https://docs.python.org/3/library/typing.html#typing.Callable">Callable</a></span><span class="p">[[],</span> <span class="kc">None</span><span class="p">]</span> <span class="o">=</span> <span class="n"><span title="derivepassphrase._internals.cli_helpers.ConfigurationMutex.__init__.unlock_func">unlock_func</span></span>
</code></pre></div>

<p>A function to unlock the mutex.</p>
<p>This implementation uses a file descriptor of a well-known file,
which is opened before locking and closed after unlocking (and on
error when locking). It will fail if the file descriptor is
unavailable. On Windows, we use <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/msvcrt.html#msvcrt.locking"><code>msvcrt.locking</code></a>, on other
systems, we use <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/fcntl.html#fcntl.flock"><code>fcntl.flock</code></a>.</p>

<details class="note" open>
  <summary>Note</summary>
  <p>This is a normal Python function, not a method.</p>
</details>

instance-attribute
  " href="#derivepassphrase._internals.cli_helpers.ConfigurationMutex.lock"><code>lock</code></a> and <a class="autorefs autorefs-internal" title="            unlock

instance-attribute
  " href="#derivepassphrase._internals.cli_helpers.ConfigurationMutex.unlock"><code>unlock</code></a> are still compatible.</p>
</details>
    </div>

</div>

<h3 id="derivepassphrase._internals.cli_helpers.ConfigurationMutex.write_lock_fileobj" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-attribute"></code>            <span class="doc doc-object-name doc-attribute-name">write_lock_fileobj</span>

<span class="doc doc-labels">
      <small class="doc doc-label doc-label-instance-attribute"><code>instance-attribute</code></small>
  </span>

<a href="#derivepassphrase._internals.cli_helpers.ConfigurationMutex.write_lock_fileobj" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><span class="n">write_lock_fileobj</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="typing.BinaryIO" href="https://docs.python.org/3/library/typing.html#typing.BinaryIO">BinaryIO</a></span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span>
</code></pre></div>

<p>The file object, if currently locked by this context manager.</p>

</div>

<h3 id="derivepassphrase._internals.cli_helpers.ConfigurationMutex.write_lock_file" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-attribute"></code>            <span class="doc doc-object-name doc-attribute-name">write_lock_file</span>

<span class="doc doc-labels">
      <small class="doc doc-label doc-label-instance-attribute"><code>instance-attribute</code></small>
  </span>

<a href="#derivepassphrase._internals.cli_helpers.ConfigurationMutex.write_lock_file" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><span class="n">write_lock_file</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="pathlib.Path" href="https://docs.python.org/3/library/pathlib.html#pathlib.Path">Path</a></span> <span class="o">=</span> <span class="n"><a class="autorefs autorefs-internal" title="            config_filename (derivepassphrase._internals.cli_helpers.config_filename)" href="#derivepassphrase._internals.cli_helpers.config_filename">config_filename</a></span><span class="p">(</span><span class="s1">&#39;write lock&#39;</span><span class="p">)</span>
</code></pre></div>

<p>The filename to lock.</p>

</div>

<h3 id="derivepassphrase._internals.cli_helpers.ConfigurationMutex.write_lock_condition" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-attribute"></code>            <span class="doc doc-object-name doc-attribute-name">write_lock_condition</span>

<span class="doc doc-labels">
      <small class="doc doc-label doc-label-instance-attribute"><code>instance-attribute</code></small>
  </span>

<a href="#derivepassphrase._internals.cli_helpers.ConfigurationMutex.write_lock_condition" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><span class="n">write_lock_condition</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="threading.Condition" href="https://docs.python.org/3/library/threading.html#threading.Condition">Condition</a></span> <span class="o">=</span> <span class="n"><a class="autorefs autorefs-external" title="threading.Condition" href="https://docs.python.org/3/library/threading.html#threading.Condition">Condition</a></span><span class="p">(</span><span class="n"><a class="autorefs autorefs-external" title="threading.Lock" href="https://docs.python.org/3/library/threading.html#threading.Lock">Lock</a></span><span class="p">())</span>
</code></pre></div>

<p>The lock protecting access to the file object.</p>

</div>

<h3 id="derivepassphrase._internals.cli_helpers.ConfigurationMutex.__enter__" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-method"></code>            <span class="doc doc-object-name doc-function-name">__enter__</span>

<a href="#derivepassphrase._internals.cli_helpers.ConfigurationMutex.__enter__" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">__enter__</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-external" title="typing_extensions.Self" href="https://typing-extensions.readthedocs.io/en/latest/index.html#typing_extensions.Self">Self</a></span>
</code></pre></div>

<p>Enter the context, locking the configuration file.</p>

</div>

<a href="#derivepassphrase._internals.cli_helpers.ConfigurationMutex.__exit__" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">__exit__</span><span class="p">(</span>
    <span class="n">exc_type</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/functions.html#type">type</a></span><span class="p">[</span><span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/exceptions.html#BaseException">BaseException</a></span><span class="p">]</span> <span class="o">|</span> <span class="kc">None</span><span class="p">,</span>
    <span class="n">exc_value</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/exceptions.html#BaseException">BaseException</a></span> <span class="o">|</span> <span class="kc">None</span><span class="p">,</span>
    <span class="n">exc_tb</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="types.TracebackType" href="https://docs.python.org/3/library/types.html#types.TracebackType">TracebackType</a></span> <span class="o">|</span> <span class="kc">None</span><span class="p">,</span>
<span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-external" title="typing.Literal" href="https://docs.python.org/3/library/typing.html#typing.Literal">Literal</a></span><span class="p">[</span><span class="kc">False</span><span class="p">]</span>
</code></pre></div>

<p>Exit the context, releasing the lock on the configuration file.</p>

</div>

<h2 id="derivepassphrase._internals.cli_helpers.ORIGIN" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code>            <span class="doc doc-object-name doc-class-name">ORIGIN</span>

<div class="doc doc-contents ">
            <p class="doc doc-class-bases">
              Bases: <code><a class="autorefs autorefs-external" title="enum.Enum" href="https://docs.python.org/3/library/enum.html#enum.Enum">Enum</a></code></p>

<p>The origin of a setting, if not from the user configuration file.</p>

<p><span class="doc-section-title">Attributes:</span></p>
    <table>
      <thead>
        <tr>
          <th>Name</th>
          <th>Type</th>
          <th>Description</th>
        </tr>
      </thead>
      <tbody>
          <tr class="doc-section-item">
            <td><code><a class="autorefs autorefs-internal" title="            INTERACTIVE

class-attribute
      instance-attribute
   (derivepassphrase._internals.cli_helpers.ORIGIN.INTERACTIVE)" href="#derivepassphrase._internals.cli_helpers.ORIGIN.INTERACTIVE">INTERACTIVE</a></code></td>
            <td>
                  <code><a class="autorefs autorefs-internal" title="            Label (derivepassphrase._internals.cli_messages.Label)" href="../derivepassphrase._internals.cli_messages/#derivepassphrase._internals.cli_messages.Label">Label</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>interactive input</p>
              </div>
            </td>
          </tr>
      </tbody>
    </table>

<h3 id="derivepassphrase._internals.cli_helpers.ORIGIN.INTERACTIVE" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-attribute"></code>            <span class="doc doc-object-name doc-attribute-name">INTERACTIVE</span>

<span class="doc doc-labels">
      <small class="doc doc-label doc-label-class-attribute"><code>class-attribute</code></small>
      <small class="doc doc-label doc-label-instance-attribute"><code>instance-attribute</code></small>
  </span>

<a href="#derivepassphrase._internals.cli_helpers.ORIGIN.INTERACTIVE" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><span class="n">INTERACTIVE</span> <span class="o">=</span> <span class="n"><span title="derivepassphrase._internals.cli_messages.Label.SETTINGS_ORIGIN_INTERACTIVE">SETTINGS_ORIGIN_INTERACTIVE</span></span>
</code></pre></div>

</div>

<h2 id="derivepassphrase._internals.cli_helpers.shell_complete_path" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">shell_complete_path</span>

<a href="#derivepassphrase._internals.cli_helpers.shell_complete_path" class="headerlink" title="Permanent link">&para;</a></h2>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">shell_complete_path</span><span class="p">(</span>
    <span class="n">ctx</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="click.Context" href="https://click.palletsprojects.com/en/stable/api/#click.Context">Context</a></span><span class="p">,</span> <span class="n">parameter</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="click.Parameter" href="https://click.palletsprojects.com/en/stable/api/#click.Parameter">Parameter</a></span><span class="p">,</span> <span class="n">value</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a></span>
<span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#list">list</a></span><span class="p">[</span><span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a></span> <span class="o">|</span> <span class="n"><a class="autorefs autorefs-external" title="click.shell_completion.CompletionItem" href="https://click.palletsprojects.com/en/stable/api/#click.shell_completion.CompletionItem">CompletionItem</a></span><span class="p">]</span>
</code></pre></div>

<p>Request standard path completion for the <code>path</code> argument.</p>

</div>

<h2 id="derivepassphrase._internals.cli_helpers.is_completable_item" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">is_completable_item</span>

<a href="#derivepassphrase._internals.cli_helpers.is_completable_item" class="headerlink" title="Permanent link">&para;</a></h2>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">is_completable_item</span><span class="p">(</span><span class="n">obj</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/functions.html#object">object</a></span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/functions.html#bool">bool</a></span>
</code></pre></div>

<p>Return whether the item is completable on the command-line.</p>
<p>The item is completable if and only if it contains no ASCII control
characters (U+0000 through U+001F, and U+007F).</p>

</div>

<h2 id="derivepassphrase._internals.cli_helpers.shell_complete_service" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">shell_complete_service</span>

<a href="#derivepassphrase._internals.cli_helpers.shell_complete_service" class="headerlink" title="Permanent link">&para;</a></h2>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">shell_complete_service</span><span class="p">(</span>
    <span class="n">ctx</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="click.Context" href="https://click.palletsprojects.com/en/stable/api/#click.Context">Context</a></span><span class="p">,</span> <span class="n">parameter</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="click.Parameter" href="https://click.palletsprojects.com/en/stable/api/#click.Parameter">Parameter</a></span><span class="p">,</span> <span class="n">value</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a></span>
<span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#list">list</a></span><span class="p">[</span><span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a></span> <span class="o">|</span> <span class="n"><a class="autorefs autorefs-external" title="click.shell_completion.CompletionItem" href="https://click.palletsprojects.com/en/stable/api/#click.shell_completion.CompletionItem">CompletionItem</a></span><span class="p">]</span>
</code></pre></div>

<p>Return known vault service names as completion items.</p>
<p>Service names are looked up in the vault configuration file.  All
errors will be suppressed.  Additionally, any service names deemed
not completable as per <a class="autorefs autorefs-internal" title="            is_completable_item" href="#derivepassphrase._internals.cli_helpers.is_completable_item"><code>is_completable_item</code></a> will be silently
skipped.</p>

</div>

<h2 id="derivepassphrase._internals.cli_helpers.configuration_mutex" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">configuration_mutex</span>

<a href="#derivepassphrase._internals.cli_helpers.configuration_mutex" class="headerlink" title="Permanent link">&para;</a></h2>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">configuration_mutex</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="p">(</span>
    <span class="n"><a class="autorefs autorefs-external" title="contextlib.AbstractContextManager" href="https://docs.python.org/3/library/contextlib.html#contextlib.AbstractContextManager">AbstractContextManager</a></span><span class="p">[</span><span class="n"><a class="autorefs autorefs-external" title="contextlib.AbstractContextManager" href="https://docs.python.org/3/library/contextlib.html#contextlib.AbstractContextManager">AbstractContextManager</a></span><span class="p">]</span>
<span class="p">)</span>
</code></pre></div>

<p>Enter a mutually exclusive context for configuration writes.</p>
<p>Within this context, no other cooperating instance of
<code>derivepassphrase</code> will attempt to write to its configuration
directory.  We achieve this by locking a specific temporary file
(whose name depends on the location of the configuration directory)
for the duration of the context.</p>

<p><span class="doc-section-title">Returns:</span></p>
    <table>
      <thead>
        <tr>
          <th>Type</th>
          <th>Description</th>
        </tr>
      </thead>
      <tbody>
          <tr class="doc-section-item">
            <td>
                  <code><a class="autorefs autorefs-external" title="contextlib.AbstractContextManager" href="https://docs.python.org/3/library/contextlib.html#contextlib.AbstractContextManager">AbstractContextManager</a>[<a class="autorefs autorefs-external" title="contextlib.AbstractContextManager" href="https://docs.python.org/3/library/contextlib.html#contextlib.AbstractContextManager">AbstractContextManager</a>]</code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>A reusable but not reentrant context manager, ensuring mutual
exclusion (while within its context) with all other
<code>derivepassphrase</code> instances using the same configuration
directory.</p>
<p>Upon entering the context, the context manager returns itself.</p>
              </div>
            </td>
          </tr>
      </tbody>
    </table>

<details class="note" open>
  <summary>Locking specifics</summary>
  <p>The directory for the lock file is determined via
<a class="autorefs autorefs-internal" title="            get_tempdir" href="#derivepassphrase._internals.cli_helpers.get_tempdir"><code>get_tempdir</code></a>.  The lock filename is
<code>derivepassphrase-lock-&lt;hash&gt;.txt</code>, where <code>&lt;hash&gt;</code> is computed
as follows.  First, canonicalize the path to the configuration
directory with <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/pathlib.html#pathlib.Path.resolve"><code>pathlib.Path.resolve</code></a>.  Then encode the
result as per the filesystem encoding (<a class="autorefs autorefs-external" href="https://docs.python.org/3/library/os.html#os.fsencode"><code>os.fsencode</code></a>), and
hash it with SHA256.  Finally, convert the result to standard
base32 and use the first twelve characters, in lowercase, as
<code>&lt;hash&gt;</code>.</p>
<p>We use <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/msvcrt.html#msvcrt.locking"><code>msvcrt.locking</code></a> on Windows platforms (<code>sys.platform
== "win32"</code>) and <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/fcntl.html#fcntl.flock"><code>fcntl.flock</code></a> on all others.  All locks are
exclusive locks.  If the locking system requires a byte range,
we lock the first <a class="autorefs autorefs-internal" title="            LOCK_SIZE

module-attribute
  " href="#derivepassphrase._internals.cli_helpers.LOCK_SIZE"><code>LOCK_SIZE</code></a> bytes.  For maximum
portability between locking implementations, we first open the
lock file for writing, which is sometimes necessary to lock
a file exclusively.  Thus locking will fail if we lack
permission to write to an already-existing lockfile.</p>
</details>

</div>

<h2 id="derivepassphrase._internals.cli_helpers.get_tempdir" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">get_tempdir</span>

<a href="#derivepassphrase._internals.cli_helpers.get_tempdir" class="headerlink" title="Permanent link">&para;</a></h2>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">get_tempdir</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-external" title="pathlib.Path" href="https://docs.python.org/3/library/pathlib.html#pathlib.Path">Path</a></span>
</code></pre></div>

<p>Return a suitable temporary directory.</p>
<p>We implement the same algorithm as <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/tempfile.html#tempfile.gettempdir"><code>tempfile.gettempdir</code></a>, except
that we default to the <code>derivepassphrase</code> configuration directory
instead of the current directory if no other choice is suitable, and
that we return <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/pathlib.html#pathlib.Path"><code>pathlib.Path</code></a> objects directly.</p>

</div>

<h2 id="derivepassphrase._internals.cli_helpers.config_filename" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">config_filename</span>

<a href="#derivepassphrase._internals.cli_helpers.config_filename" class="headerlink" title="Permanent link">&para;</a></h2>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">config_filename</span><span class="p">(</span>
    <span class="n">subsystem</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a></span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="s2">&quot;old settings.json&quot;</span><span class="p">,</span>
<span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-external" title="pathlib.Path" href="https://docs.python.org/3/library/pathlib.html#pathlib.Path">Path</a></span>
</code></pre></div>

<p>Return the filename of the configuration file for the subsystem.</p>
<p>The (implicit default) file is currently named <code>settings.json</code>,
located within the configuration directory as determined by the
<code>DERIVEPASSPHRASE_PATH</code> environment variable, or by
<a class="autorefs autorefs-external" href="https://click.palletsprojects.com/en/stable/api/#click.get_app_dir"><code>click.get_app_dir</code></a> in POSIX mode.  Depending on the requested
subsystem, this will usually be a different file within that
directory.</p>

<details class="deprecated" open>
  <summary>Deprecated</summary>
  <p>Since v0.2.0: The implicit default subsystem and the old
configuration filename are deprecated, and will be removed in v1.0.
The subsystem will be mandatory to specify.</p>
</details>

</div>

<h2 id="derivepassphrase._internals.cli_helpers.load_config" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">load_config</span>

<a href="#derivepassphrase._internals.cli_helpers.load_config" class="headerlink" title="Permanent link">&para;</a></h2>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">load_config</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-internal" title="            VaultConfig (derivepassphrase._types.VaultConfig)" href="../derivepassphrase._types/#derivepassphrase._types.VaultConfig">VaultConfig</a></span>
</code></pre></div>

<p>Load a vault(1)-compatible config from the application directory.</p>
<p>The filename is obtained via <a class="autorefs autorefs-internal" title="            config_filename" href="#derivepassphrase._internals.cli_helpers.config_filename"><code>config_filename</code></a>.  This must be
an unencrypted JSON file.</p>

<p><span class="doc-section-title">Returns:</span></p>
    <table>
      <thead>
        <tr>
          <th>Type</th>
          <th>Description</th>
        </tr>
      </thead>
      <tbody>
          <tr class="doc-section-item">
            <td>
                  <code><a class="autorefs autorefs-internal" title="            VaultConfig (derivepassphrase._types.VaultConfig)" href="../derivepassphrase._types/#derivepassphrase._types.VaultConfig">VaultConfig</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The vault settings.  See <a class="autorefs autorefs-internal" title="            VaultConfig" href="../derivepassphrase._types/#derivepassphrase._types.VaultConfig"><code>_types.VaultConfig</code></a> for details.</p>
              </div>
            </td>
          </tr>
      </tbody>
    </table>

</div>

<h2 id="derivepassphrase._internals.cli_helpers.migrate_and_load_old_config" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">migrate_and_load_old_config</span>

<a href="#derivepassphrase._internals.cli_helpers.migrate_and_load_old_config" class="headerlink" title="Permanent link">&para;</a></h2>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">migrate_and_load_old_config</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="p">(</span>
    <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#tuple">tuple</a></span><span class="p">[</span><span class="n"><a class="autorefs autorefs-internal" title="            VaultConfig (derivepassphrase._types.VaultConfig)" href="../derivepassphrase._types/#derivepassphrase._types.VaultConfig">VaultConfig</a></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/exceptions.html#OSError">OSError</a></span> <span class="o">|</span> <span class="kc">None</span><span class="p">]</span>
<span class="p">)</span>
</code></pre></div>

<p>Load and migrate a vault(1)-compatible config.</p>
<p>The (old) filename is obtained via <a class="autorefs autorefs-internal" title="            config_filename" href="#derivepassphrase._internals.cli_helpers.config_filename"><code>config_filename</code></a>.  This
must be an unencrypted JSON file.  After loading, the file is
migrated to the new standard filename.</p>

<p><span class="doc-section-title">Returns:</span></p>
    <table>
      <thead>
        <tr>
          <th>Type</th>
          <th>Description</th>
        </tr>
      </thead>
      <tbody>
          <tr class="doc-section-item">
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#tuple">tuple</a>[<a class="autorefs autorefs-internal" title="            VaultConfig (derivepassphrase._types.VaultConfig)" href="../derivepassphrase._types/#derivepassphrase._types.VaultConfig">VaultConfig</a>, <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/exceptions.html#OSError">OSError</a> | None]</code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The vault settings, and an optional exception encountered during
migration.  See <a class="autorefs autorefs-internal" title="            VaultConfig" href="../derivepassphrase._types/#derivepassphrase._types.VaultConfig"><code>_types.VaultConfig</code></a> for details on the
former.</p>
              </div>
            </td>
          </tr>
      </tbody>
    </table>

</div>

<h2 id="derivepassphrase._internals.cli_helpers.save_config" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">save_config</span>

<a href="#derivepassphrase._internals.cli_helpers.save_config" class="headerlink" title="Permanent link">&para;</a></h2>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">save_config</span><span class="p">(</span><span class="n">config</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="            VaultConfig (derivepassphrase._types.VaultConfig)" href="../derivepassphrase._types/#derivepassphrase._types.VaultConfig">VaultConfig</a></span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span>
</code></pre></div>

<p>Save a vault(1)-compatible config to the application directory.</p>
<p>The filename is obtained via <a class="autorefs autorefs-internal" title="            config_filename" href="#derivepassphrase._internals.cli_helpers.config_filename"><code>config_filename</code></a>.  The config
will be stored as an unencrypted JSON file.</p>

</div>

<h2 id="derivepassphrase._internals.cli_helpers.load_user_config" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">load_user_config</span>

<a href="#derivepassphrase._internals.cli_helpers.load_user_config" class="headerlink" title="Permanent link">&para;</a></h2>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">load_user_config</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#dict">dict</a></span><span class="p">[</span><span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-external" title="typing_extensions.Any" href="https://typing-extensions.readthedocs.io/en/latest/index.html#typing_extensions.Any">Any</a></span><span class="p">]</span>
</code></pre></div>

<p>Load the user config from the application directory.</p>
<p>The filename is obtained via <a class="autorefs autorefs-internal" title="            config_filename" href="#derivepassphrase._internals.cli_helpers.config_filename"><code>config_filename</code></a>.</p>

<p><span class="doc-section-title">Returns:</span></p>
    <table>
      <thead>
        <tr>
          <th>Type</th>
          <th>Description</th>
        </tr>
      </thead>
      <tbody>
          <tr class="doc-section-item">
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#dict">dict</a>[<a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a>, <a class="autorefs autorefs-external" title="typing_extensions.Any" href="https://typing-extensions.readthedocs.io/en/latest/index.html#typing_extensions.Any">Any</a>]</code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The user configuration, as a nested <code>dict</code>.</p>
              </div>
            </td>
          </tr>
      </tbody>
    </table>

</div>

<h2 id="derivepassphrase._internals.cli_helpers.get_suitable_ssh_keys" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">get_suitable_ssh_keys</span>

<a href="#derivepassphrase._internals.cli_helpers.get_suitable_ssh_keys" class="headerlink" title="Permanent link">&para;</a></h2>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">get_suitable_ssh_keys</span><span class="p">(</span>
    <span class="n">conn</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="            SSHAgentClient (derivepassphrase.ssh_agent.SSHAgentClient)" href="../derivepassphrase.ssh_agent/#derivepassphrase.ssh_agent.SSHAgentClient">SSHAgentClient</a></span> <span class="o">|</span> <span class="n"><a class="autorefs autorefs-external" title="socket.socket" href="https://docs.python.org/3/library/socket.html#socket.socket">socket</a></span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
<span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-external" title="collections.abc.Iterator" href="https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterator">Iterator</a></span><span class="p">[</span><span class="n"><a class="autorefs autorefs-internal" title="            SSHKeyCommentPair (derivepassphrase._types.SSHKeyCommentPair)" href="../derivepassphrase._types/#derivepassphrase._types.SSHKeyCommentPair">SSHKeyCommentPair</a></span><span class="p">]</span>
</code></pre></div>

<p>Yield all SSH keys suitable for passphrase derivation.</p>
<p>Suitable SSH keys are queried from the running SSH agent (see
<a class="autorefs autorefs-internal" title="            list_keys" href="../derivepassphrase.ssh_agent/#derivepassphrase.ssh_agent.SSHAgentClient.list_keys"><code>ssh_agent.SSHAgentClient.list_keys</code></a>).</p>

<p><span class="doc-section-title">Yields:</span></p>
    <table>
      <thead>
        <tr>
          <th>Type</th>
          <th>Description</th>
        </tr>
      </thead>
      <tbody>
          <tr class="doc-section-item">
            <td>
                  <code><a class="autorefs autorefs-internal" title="            SSHKeyCommentPair (derivepassphrase._types.SSHKeyCommentPair)" href="../derivepassphrase._types/#derivepassphrase._types.SSHKeyCommentPair">SSHKeyCommentPair</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>Every SSH key from the SSH agent that is suitable for passphrase
derivation.</p>
              </div>
            </td>
          </tr>
      </tbody>
    </table>

<p><span class="doc-section-title">Raises:</span></p>
    <table>
      <thead>
        <tr>
          <th>Type</th>
          <th>Description</th>
        </tr>
      </thead>
      <tbody>
          <tr class="doc-section-item">
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/exceptions.html#KeyError">KeyError</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p><code>conn</code> was <code>None</code>, and the <code>SSH_AUTH_SOCK</code> environment
variable was not found.</p>
              </div>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/exceptions.html#NotImplementedError">NotImplementedError</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p><code>conn</code> was <code>None</code>, and this Python does not support
<a class="autorefs autorefs-external" href="https://docs.python.org/3/library/socket.html#socket.AF_UNIX"><code>socket.AF_UNIX</code></a>, so the SSH agent client cannot be
automatically set up.</p>
              </div>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/exceptions.html#OSError">OSError</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p><code>conn</code> was a socket or <code>None</code>, and there was an error
setting up a socket connection to the agent.</p>
              </div>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/exceptions.html#LookupError">LookupError</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>No keys usable for passphrase derivation are loaded into the
SSH agent.</p>
              </div>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/exceptions.html#RuntimeError">RuntimeError</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>There was an error communicating with the SSH agent.</p>
              </div>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                  <code><a class="autorefs autorefs-internal" title="            SSHAgentFailedError (derivepassphrase.ssh_agent.SSHAgentFailedError)" href="../derivepassphrase.ssh_agent/#derivepassphrase.ssh_agent.SSHAgentFailedError">SSHAgentFailedError</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The agent failed to supply a list of loaded keys.</p>
              </div>
            </td>
          </tr>
      </tbody>
    </table>

</div>

<h2 id="derivepassphrase._internals.cli_helpers.prompt_for_selection" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">prompt_for_selection</span>

<a href="#derivepassphrase._internals.cli_helpers.prompt_for_selection" class="headerlink" title="Permanent link">&para;</a></h2>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">prompt_for_selection</span><span class="p">(</span>
    <span class="n">items</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="collections.abc.Sequence" href="https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence">Sequence</a></span><span class="p">[</span><span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a></span> <span class="o">|</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytes">bytes</a></span><span class="p">],</span>
    <span class="n">heading</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a></span> <span class="o">=</span> <span class="s2">&quot;Possible choices:&quot;</span><span class="p">,</span>
    <span class="n">single_choice_prompt</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a></span> <span class="o">=</span> <span class="s2">&quot;Confirm this choice?&quot;</span><span class="p">,</span>
    <span class="n">ctx</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="click.Context" href="https://click.palletsprojects.com/en/stable/api/#click.Context">Context</a></span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
<span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/functions.html#int">int</a></span>
</code></pre></div>

<p>Prompt user for a choice among the given items.</p>
<p>Print the heading, if any, then present the items to the user.  If
there are multiple items, prompt the user for a selection, validate
the choice, then return the list index of the selected item.  If
there is only a single item, request confirmation for that item
instead, and return the correct index.</p>

<p><span class="doc-section-title">Parameters:</span></p>
    <table>
      <thead>
        <tr>
          <th>Name</th>
          <th>Type</th>
          <th>Description</th>
          <th>Default</th>
        </tr>
      </thead>
      <tbody>
          <tr class="doc-section-item">
            <td>
                <code>items</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-external" title="collections.abc.Sequence" href="https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence">Sequence</a>[<a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a> | <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytes">bytes</a>]</code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The list of items to choose from.</p>
              </div>
            </td>
            <td>
                <em>required</em>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                <code>heading</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>A heading for the list of items, to print immediately
before.  Defaults to a reasonable standard heading.  If
explicitly empty, print no heading.</p>
              </div>
            </td>
            <td>
                  <code>&#39;Possible choices:&#39;</code>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                <code>single_choice_prompt</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The confirmation prompt if there is only a single possible
choice.  Defaults to a reasonable standard prompt.</p>
              </div>
            </td>
            <td>
                  <code>&#39;Confirm this choice?&#39;</code>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                <code>ctx</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-external" title="click.Context" href="https://click.palletsprojects.com/en/stable/api/#click.Context">Context</a> | None</code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>An optional <code>click</code> context, from which output device
properties and color preferences will be queried.</p>
              </div>
            </td>
            <td>
                  <code>None</code>
            </td>
          </tr>
      </tbody>
    </table>

</div>

<h2 id="derivepassphrase._internals.cli_helpers.select_ssh_key" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">select_ssh_key</span>

<a href="#derivepassphrase._internals.cli_helpers.select_ssh_key" class="headerlink" title="Permanent link">&para;</a></h2>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">select_ssh_key</span><span class="p">(</span>
    <span class="n">conn</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="            SSHAgentClient (derivepassphrase.ssh_agent.SSHAgentClient)" href="../derivepassphrase.ssh_agent/#derivepassphrase.ssh_agent.SSHAgentClient">SSHAgentClient</a></span> <span class="o">|</span> <span class="n"><a class="autorefs autorefs-external" title="socket.socket" href="https://docs.python.org/3/library/socket.html#socket.socket">socket</a></span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
    <span class="o">/</span><span class="p">,</span>
    <span class="o">*</span><span class="p">,</span>
    <span class="n">ctx</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="click.Context" href="https://click.palletsprojects.com/en/stable/api/#click.Context">Context</a></span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
<span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytes">bytes</a></span> <span class="o">|</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytearray">bytearray</a></span>
</code></pre></div>

<p>Interactively select an SSH key for passphrase derivation.</p>
<p>Suitable SSH keys are queried from the running SSH agent (see
<a class="autorefs autorefs-internal" title="            list_keys" href="../derivepassphrase.ssh_agent/#derivepassphrase.ssh_agent.SSHAgentClient.list_keys"><code>ssh_agent.SSHAgentClient.list_keys</code></a>), then the user is prompted
interactively (see <a class="autorefs autorefs-external" href="https://click.palletsprojects.com/en/stable/api/#click.prompt"><code>click.prompt</code></a>) for a selection.</p>

classmethod
  " href="../derivepassphrase.ssh_agent/#derivepassphrase.ssh_agent.SSHAgentClient.ensure_agent_subcontext"><code>ssh_agent.SSHAgentClient.ensure_agent_subcontext</code></a>.</p>
              </div>
            </td>
            <td>
                  <code>None</code>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                <code>ctx</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-external" title="click.Context" href="https://click.palletsprojects.com/en/stable/api/#click.Context">Context</a> | None</code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>An <code>click</code> context, queried for output device properties and
color preferences when issuing the prompt.</p>
              </div>
            </td>
            <td>
                  <code>None</code>
            </td>
          </tr>
      </tbody>
    </table>

<p><span class="doc-section-title">Raises:</span></p>
    <table>
      <thead>
        <tr>
          <th>Type</th>
          <th>Description</th>
        </tr>
      </thead>
      <tbody>
          <tr class="doc-section-item">
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/exceptions.html#KeyError">KeyError</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p><code>conn</code> was <code>None</code>, and the <code>SSH_AUTH_SOCK</code> environment
variable was not found.</p>
              </div>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/exceptions.html#NotImplementedError">NotImplementedError</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p><code>conn</code> was <code>None</code>, and this Python does not support
<a class="autorefs autorefs-external" href="https://docs.python.org/3/library/socket.html#socket.AF_UNIX"><code>socket.AF_UNIX</code></a>, so the SSH agent client cannot be
automatically set up.</p>
              </div>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/exceptions.html#OSError">OSError</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p><code>conn</code> was a socket or <code>None</code>, and there was an error
setting up a socket connection to the agent.</p>
              </div>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/exceptions.html#IndexError">IndexError</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The user made an invalid or empty selection, or requested an
abort.</p>
              </div>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/exceptions.html#LookupError">LookupError</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>No keys usable for passphrase derivation are loaded into the
SSH agent.</p>
              </div>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/exceptions.html#RuntimeError">RuntimeError</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>There was an error communicating with the SSH agent.</p>
              </div>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                  <code><span title="SSHAgentFailedError">SSHAgentFailedError</span></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The agent failed to supply a list of loaded keys.</p>
              </div>
            </td>
          </tr>
      </tbody>
    </table>

</div>

<h2 id="derivepassphrase._internals.cli_helpers.prompt_for_passphrase" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">prompt_for_passphrase</span>

<a href="#derivepassphrase._internals.cli_helpers.prompt_for_passphrase" class="headerlink" title="Permanent link">&para;</a></h2>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">prompt_for_passphrase</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a></span>
</code></pre></div>

<p>Interactively prompt for the passphrase.</p>
<p>Calls <a class="autorefs autorefs-external" href="https://click.palletsprojects.com/en/stable/api/#click.prompt"><code>click.prompt</code></a> internally.  Moved into a separate function
mainly for testing/mocking purposes.</p>

</div>

<a href="#derivepassphrase._internals.cli_helpers.toml_key" class="headerlink" title="Permanent link">&para;</a></h2>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">toml_key</span><span class="p">(</span><span class="o">*</span><span class="n">parts</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a></span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a></span>
</code></pre></div>

<p>Return a formatted TOML key, given its parts.</p>

</div>

<h2 id="derivepassphrase._internals.cli_helpers.check_for_misleading_passphrase" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">check_for_misleading_passphrase</span>

<a href="#derivepassphrase._internals.cli_helpers.check_for_misleading_passphrase" class="headerlink" title="Permanent link">&para;</a></h2>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">check_for_misleading_passphrase</span><span class="p">(</span>
    <span class="n">key</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#tuple">tuple</a></span><span class="p">[</span><span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a></span><span class="p">,</span> <span class="o">...</span><span class="p">]</span> <span class="o">|</span> <span class="n"><a class="autorefs autorefs-internal" title="            ORIGIN (derivepassphrase._internals.cli_helpers.ORIGIN)" href="#derivepassphrase._internals.cli_helpers.ORIGIN">ORIGIN</a></span><span class="p">,</span>
    <span class="n">value</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="collections.abc.Mapping" href="https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping">Mapping</a></span><span class="p">[</span><span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-external" title="typing_extensions.Any" href="https://typing-extensions.readthedocs.io/en/latest/index.html#typing_extensions.Any">Any</a></span><span class="p">],</span>
    <span class="o">*</span><span class="p">,</span>
    <span class="n">main_config</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#dict">dict</a></span><span class="p">[</span><span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-external" title="typing_extensions.Any" href="https://typing-extensions.readthedocs.io/en/latest/index.html#typing_extensions.Any">Any</a></span><span class="p">],</span>
    <span class="n">ctx</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="click.Context" href="https://click.palletsprojects.com/en/stable/api/#click.Context">Context</a></span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span>
<span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span>
</code></pre></div>

<p>Check for a misleading passphrase according to user configuration.</p>
<p>Look up the desired Unicode normalization form in the user
configuration, and if the passphrase is not normalized according to
this form, issue a warning to the user.</p>

class-attribute
      instance-attribute
  " href="#derivepassphrase._internals.cli_helpers.ORIGIN.INTERACTIVE"><code>ORIGIN.INTERACTIVE</code></a>,
or <code>("global",)</code>, or <code>("services", "foo")</code>.</p>
              </div>
            </td>
            <td>
                <em>required</em>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                <code>value</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-external" title="collections.abc.Mapping" href="https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping">Mapping</a>[<a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a>, <a class="autorefs autorefs-external" title="typing_extensions.Any" href="https://typing-extensions.readthedocs.io/en/latest/index.html#typing_extensions.Any">Any</a>]</code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The vault configuration section maybe containing
a passphrase to vet.</p>
              </div>
            </td>
            <td>
                <em>required</em>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                <code>main_config</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#dict">dict</a>[<a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a>, <a class="autorefs autorefs-external" title="typing_extensions.Any" href="https://typing-extensions.readthedocs.io/en/latest/index.html#typing_extensions.Any">Any</a>]</code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The parsed main user configuration.</p>
              </div>
            </td>
            <td>
                <em>required</em>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                <code>ctx</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-external" title="click.Context" href="https://click.palletsprojects.com/en/stable/api/#click.Context">Context</a> | None</code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The click context.  This is necessary to pass output options
set on the context to the logging machinery.</p>
              </div>
            </td>
            <td>
                  <code>None</code>
            </td>
          </tr>
      </tbody>
    </table>

</div>

<h2 id="derivepassphrase._internals.cli_helpers.default_error_callback" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">default_error_callback</span>

<a href="#derivepassphrase._internals.cli_helpers.default_error_callback" class="headerlink" title="Permanent link">&para;</a></h2>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">default_error_callback</span><span class="p">(</span>
    <span class="n">message</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="typing_extensions.Any" href="https://typing-extensions.readthedocs.io/en/latest/index.html#typing_extensions.Any">Any</a></span><span class="p">,</span> <span class="o">/</span><span class="p">,</span> <span class="o">*</span><span class="n">_args</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="typing_extensions.Any" href="https://typing-extensions.readthedocs.io/en/latest/index.html#typing_extensions.Any">Any</a></span><span class="p">,</span> <span class="o">**</span><span class="n">_kwargs</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="typing_extensions.Any" href="https://typing-extensions.readthedocs.io/en/latest/index.html#typing_extensions.Any">Any</a></span>
<span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-external" title="typing.NoReturn" href="https://docs.python.org/3/library/typing.html#typing.NoReturn">NoReturn</a></span>
</code></pre></div>

<p>Calls <a class="autorefs autorefs-external" href="https://docs.python.org/3/library/sys.html#sys.exit"><code>sys.exit</code></a> on its first argument, ignoring the rest.</p>

</div>

<h2 id="derivepassphrase._internals.cli_helpers.key_to_phrase" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">key_to_phrase</span>

<a href="#derivepassphrase._internals.cli_helpers.key_to_phrase" class="headerlink" title="Permanent link">&para;</a></h2>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">key_to_phrase</span><span class="p">(</span>
    <span class="n">key</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a></span> <span class="o">|</span> <span class="n"><a class="autorefs autorefs-external" title="typing_extensions.Buffer" href="https://typing-extensions.readthedocs.io/en/latest/index.html#typing_extensions.Buffer">Buffer</a></span><span class="p">,</span>
    <span class="o">/</span><span class="p">,</span>
    <span class="o">*</span><span class="p">,</span>
    <span class="n">error_callback</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="typing.Callable" href="https://docs.python.org/3/library/typing.html#typing.Callable">Callable</a></span><span class="p">[</span>
        <span class="o">...</span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-external" title="typing.NoReturn" href="https://docs.python.org/3/library/typing.html#typing.NoReturn">NoReturn</a></span>
    <span class="p">]</span> <span class="o">=</span> <span class="n"><a class="autorefs autorefs-internal" title="            default_error_callback (derivepassphrase._internals.cli_helpers.default_error_callback)" href="#derivepassphrase._internals.cli_helpers.default_error_callback">default_error_callback</a></span><span class="p">,</span>
<span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#bytes">bytes</a></span>
</code></pre></div>

<p>Return the equivalent master passphrase, or abort.</p>
<p>This wrapper around <a class="autorefs autorefs-internal" title="            phrase_from_key

classmethod
  " href="../derivepassphrase.vault/#derivepassphrase.vault.Vault.phrase_from_key"><code>vault.Vault.phrase_from_key</code></a> emits
user-facing error messages if no equivalent master passphrase can be
obtained from the key, because this is the first point of contact
with the SSH agent.</p>

</div>

<h2 id="derivepassphrase._internals.cli_helpers.print_config_as_sh_script" class="doc doc-heading">
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">print_config_as_sh_script</span>

<a href="#derivepassphrase._internals.cli_helpers.print_config_as_sh_script" class="headerlink" title="Permanent link">&para;</a></h2>
<div class="doc-signature highlight"><pre><span></span><code><span class="nf">print_config_as_sh_script</span><span class="p">(</span>
    <span class="n">config</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="            VaultConfig (derivepassphrase._types.VaultConfig)" href="../derivepassphrase._types/#derivepassphrase._types.VaultConfig">VaultConfig</a></span><span class="p">,</span>
    <span class="o">/</span><span class="p">,</span>
    <span class="o">*</span><span class="p">,</span>
    <span class="n">outfile</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="typing.TextIO" href="https://docs.python.org/3/library/typing.html#typing.TextIO">TextIO</a></span><span class="p">,</span>
    <span class="n">prog_name_list</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="collections.abc.Sequence" href="https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence">Sequence</a></span><span class="p">[</span><span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a></span><span class="p">],</span>
<span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span>
</code></pre></div>

<p>Print the given vault configuration as a sh(1) script.</p>
<p>This implements the <code>--export-as=sh</code> option of <code>derivepassphrase vault</code>.</p>

<p><span class="doc-section-title">Parameters:</span></p>
    <table>
      <thead>
        <tr>
          <th>Name</th>
          <th>Type</th>
          <th>Description</th>
          <th>Default</th>
        </tr>
      </thead>
      <tbody>
          <tr class="doc-section-item">
            <td>
                <code>config</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-internal" title="            VaultConfig (derivepassphrase._types.VaultConfig)" href="../derivepassphrase._types/#derivepassphrase._types.VaultConfig">VaultConfig</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>The configuration to serialize.</p>
              </div>
            </td>
            <td>
                <em>required</em>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                <code>outfile</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-external" title="typing.TextIO" href="https://docs.python.org/3/library/typing.html#typing.TextIO">TextIO</a></code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>A file object to write the output to.</p>
              </div>
            </td>
            <td>
                <em>required</em>
            </td>
          </tr>
          <tr class="doc-section-item">
            <td>
                <code>prog_name_list</code>
            </td>
            <td>
                  <code><a class="autorefs autorefs-external" title="collections.abc.Sequence" href="https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence">Sequence</a>[<a class="autorefs autorefs-external" href="https://docs.python.org/3/library/stdtypes.html#str">str</a>]</code>
            </td>
            <td>
              <div class="doc-md-description">
                <p>A list of (subcommand) names for the command emitting this
output, e.g. <code>["derivepassphrase", "vault"]</code>.</p>
              </div>
            </td>
            <td>
                <em>required</em>
            </td>
          </tr>
      </tbody>
    </table>

</div>

</article>
            </div>
          
          
        </div>
        
      </main>
      
        <footer class="md-footer">
  
    
  
  <div class="md-footer-meta md-typeset">
    <div class="md-footer-meta__inner md-grid">
      <div class="md-copyright">
  
    <div class="md-copyright__highlight">
      Copyright &copy; 2025 Marco Ricci (the-13th-letter)
    </div>
  
  
    Made with
    <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
      Material for MkDocs
    </a>
    and
    <a href="https://mkdocstrings.github.io/python/" target="_blank" rel="noopener">
        mkdocstrings-python
    </a>
  
</div>
      
    </div>
  </div>
</footer>
      
    </div>
    <div class="md-dialog" data-md-component="dialog">
      <div class="md-dialog__inner md-typeset"></div>
    </div>
    
    
    
    
  </body>
</html>

derivepassphrase.git

Deployed 1888df51e637 to 0.x with MkDocs 1.6.1 and mike 2.1.3