py36/library/configparser.html at master · python-doc-ja/py36

History

1151 lines (1054 loc) · 144 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

391

392

393

394

395

396

397

398

399

400

401

402

403

404

405

406

407

408

409

410

411

412

413

414

415

416

417

418

419

420

421

422

423

424

425

426

427

428

429

430

431

432

433

434

435

436

437

438

439

440

441

442

443

444

445

446

447

448

449

450

451

452

453

454

455

456

457

458

459

460

461

462

463

464

465

466

467

468

469

470

471

472

473

474

475

476

477

478

479

480

481

482

483

484

485

486

487

488

489

490

491

492

493

494

495

496

497

498

499

500

501

502

503

504

505

506

507

508

509

510

511

512

513

514

515

516

517

518

519

520

521

522

523

524

525

526

527

528

529

530

531

532

533

534

535

536

537

538

539

540

541

542

543

544

545

546

547

548

549

550

551

552

553

554

555

556

557

558

559

560

561

562

563

564

565

566

567

568

569

570

571

572

573

574

575

576

577

578

579

580

581

582

583

584

585

586

587

588

589

590

591

592

593

594

595

596

597

598

599

600

601

602

603

604

605

606

607

608

609

610

611

612

613

614

615

616

617

618

619

620

621

622

623

624

625

626

627

628

629

630

631

632

633

634

635

636

637

638

639

640

641

642

643

644

645

646

647

648

649

650

651

652

653

654

655

656

657

658

659

660

661

662

663

664

665

666

667

668

669

670

671

672

673

674

675

676

677

678

679

680

681

682

683

684

685

686

687

688

689

690

691

692

693

694

695

696

697

698

699

700

701

702

703

704

705

706

707

708

709

710

711

712

713

714

715

716

717

718

719

720

721

722

723

724

725

726

727

728

729

730

731

732

733

734

735

736

737

738

739

740

741

742

743

744

745

746

747

748

749

750

751

752

753

754

755

756

757

758

759

760

761

762

763

764

765

766

767

768

769

770

771

772

773

774

775

776

777

778

779

780

781

782

783

784

785

786

787

788

789

790

791

792

793

794

795

796

797

798

799

800

801

802

803

804

805

806

807

808

809

810

811

812

813

814

815

816

817

818

819

820

821

822

823

824

825

826

827

828

829

830

831

832

833

834

835

836

837

838

839

840

841

842

843

844

845

846

847

848

849

850

851

852

853

854

855

856

857

858

859

860

861

862

863

864

865

866

867

868

869

870

871

872

873

874

875

876

877

878

879

880

881

882

883

884

885

886

887

888

889

890

891

892

893

894

895

896

897

898

899

900

901

902

903

904

905

906

907

908

909

910

911

912

913

914

915

916

917

918

919

920

921

922

923

924

925

926

927

928

929

930

931

932

933

934

935

936

937

938

939

940

941

942

943

944

945

946

947

948

949

950

951

952

953

954

955

956

957

958

959

960

961

962

963

964

965

966

967

968

969

970

971

972

973

974

975

976

977

978

979

980

981

982

983

984

985

986

987

988

989

990

991

992

993

994

995

996

997

998

999

1000

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<head>

<title>14.2. configparser — 設定ファイルのパーサー — Python 3.6.5 ドキュメント</title>

var DOCUMENTATION_OPTIONS = {

URL_ROOT: '../',

VERSION: '3.6.5',

COLLAPSE_INDEX: false,

FILE_SUFFIX: '.html',

HAS_SOURCE: true,

SOURCELINK_SUFFIX: '.txt'

};

</script>

title="Python 3.6.5 ドキュメント内を検索"

href="../_static/opensearch.xml"/>

$(document).ready(function() {

var base = 'https://docs.python.org/3.6/library/configparser.html';

$('a.headerlink').each(function() {

var html = '<a href="' + base + $(this).attr('href') +

'" title="原文へのリンク">(原文)</a>';

$(this).after(html);

})

});

</script>

</head>

<body>

<h3>ナビゲーション</h3>

<ul>

<a href="../genindex.html" title="総索引"

accesskey="I">索引</a></li>

<a href="../py-modindex.html" title="Pythonモジュール索引"

>モジュール</a> |</li>

<a href="netrc.html" title="14.3. netrc — netrc ファイルの処理"

accesskey="N">次へ</a> |</li>

<a href="csv.html" title="14.1. csv — CSV ファイルの読み書き"

accesskey="P">前へ</a> |</li>

<li><img src="../_static/py.png" alt=""

style="vertical-align: middle; margin-top: -1px"/></li>

<li><a href="https://www.python.org/">Python</a> »</li>

<li>

3.6.5

<a href="../index.html">ドキュメント</a> »

</li>

<li class="nav-item nav-item-1"><a href="index.html" >Python 標準ライブラリ</a> »</li>

<li class="nav-item nav-item-2"><a href="fileformats.html" accesskey="U">14. ファイルフォーマット</a> »</li>

</form>

</div>

</li>

</ul>

</div>

<h1>14.2. <a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal">configparser</code></a> — 設定ファイルのパーサー<a class="headerlink" href="#module-configparser" title="このヘッドラインへのパーマリンク">¶</a></h1>

ソースコード: <a class="reference external" href="https://github.com/python/cpython/tree/3.6/Lib/configparser.py">Lib/configparser.py</a>

このモジュールは、 Microsoft Windows の INI ファイルに似た構造を持ったベーシックな設定用言語を実装した <a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal">ConfigParser</code></a> クラスを提供します。このクラスを使ってユーザーが簡単にカスタマイズできる Python プログラムを作ることができます。

注釈

このライブラリでは、Windowsのレジストリ用に拡張された INI 文法はサポート していません 。

</div>

参考

<dt><a class="reference internal" href="shlex.html#module-shlex" title="shlex: Simple lexical analysis for Unix shell-like languages."><code class="xref py py-mod docutils literal">shlex</code></a> モジュール</dt>

<dd>アプリケーション設定ファイルのフォーマットとして使える、Unix シェルに似たミニ言語の作成を支援します。</dd>

<dt><a class="reference internal" href="json.html#module-json" title="json: Encode and decode the JSON format."><code class="xref py py-mod docutils literal">json</code></a> モジュール</dt>

<dd>json モジュールは、同じ目的に利用できる JavaScript の文法のサブセットを実装しています。</dd>

</dl>

</div>

<h2>14.2.1. クイックスタート<a class="headerlink" href="#quick-start" title="このヘッドラインへのパーマリンク">¶</a></h2>

次のような、非常に簡単な設定ファイルを例に考えましょう:

<div class="highlight-ini"><div class="highlight"><pre>[DEFAULT]

ServerAliveInterval = 45

Compression = yes

CompressionLevel = 9

ForwardX11 = yes

[bitbucket.org]

User = hg

[topsecret.server.com]

Port = 50022

ForwardX11 = no

</pre></div>

</div>

INI ファイルの構造は <a class="reference external" href="#supported-ini-file-structure">下のセクション</a> で解説します。

基本的に、ファイルは複数のセクションからなり、各セクションは複数のキーと値を持ちます。

<a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal">configparser</code></a> のクラス群はそれらのファイルを読み書きできます。

まずは上のような設定ファイルをプログラムから作成してみましょう。

<div class="highlight-python3"><div class="highlight"><pre>>>> import configparser

>>> config['DEFAULT'] = {'ServerAliveInterval': '45',

... 'Compression': 'yes',

... 'CompressionLevel': '9'}

>>> config['bitbucket.org'] = {}

>>> config['bitbucket.org']['User'] = 'hg'

>>> config['topsecret.server.com'] = {}

>>> topsecret = config['topsecret.server.com']

>>> topsecret['Port'] = '50022' # mutates the parser

>>> topsecret['ForwardX11'] = 'no' # same here

>>> config['DEFAULT']['ForwardX11'] = 'yes'

>>> with open('example.ini', 'w') as configfile:

... config.write(configfile)

...

</pre></div>

</div>

この例でわかるように、config parser は辞書のように扱うことができます。辞書との違いは <a class="reference external" href="#mapping-protocol-access">後に</a> 説明しますが、このインターフェイスは辞書に対して期待するのととても近い動作をします。

これで設定ファイルを作成して保存できました。次はこれを読み込み直して、中のデータを取り出してみましょう。

<div class="highlight-python3"><div class="highlight"><pre>>>> import configparser

>>> config.sections()

[]

>>> config.read('example.ini')

['example.ini']

>>> config.sections()

['bitbucket.org', 'topsecret.server.com']

>>> 'bitbucket.org' in config

True

>>> 'bytebong.com' in config

False

>>> config['bitbucket.org']['User']

'hg'

'yes'

>>> topsecret['ForwardX11']

'no'

>>> topsecret['Port']

'50022'

>>> for key in config['bitbucket.org']: print(key)

...

user

compressionlevel

serveraliveinterval

compression

forwardx11

'yes'

</pre></div>

</div>

上の例からわかるように、API はとても直感的です。唯一の魔術は、<code class="docutils literal">DEFAULT</code> セクションが他の全てのセクションのためのデフォルト値を提供していることです <a class="footnote-reference" href="#id14" id="id2">[1]</a>。また、セクション内の各キーは大文字小文字を区別せず、全て小文字で保存されていることにも注意してください <a class="footnote-reference" href="#id14" id="id2">[1]</a>。

</div>

<h2>14.2.2. サポートされるデータ型<a class="headerlink" href="#supported-datatypes" title="このヘッドラインへのパーマリンク">¶</a></h2>

Config parser は値のデータ型について何も推論せず、常に文字列のまま内部に保存します。他のデータ型が必要な場合は自分で変換する必要があります:

<div class="highlight-python3"><div class="highlight"><pre>>>> int(topsecret['Port'])

50022

>>> float(topsecret['CompressionLevel'])

9.0

</pre></div>

</div>

このタスクはとても一般的なため、設定パーサーでは整数、浮動小数点数、真偽値を扱うための手頃なゲッターメソッドが提供されています。真偽値の扱いは一筋縄ではいきません。文字列を <code class="docutils literal">bool()</code> に渡しても、 <code class="docutils literal">bool('False')</code> が <code class="docutils literal">True</code> になってしまいます。そこで config parser は <a class="reference internal" href="#configparser.ConfigParser.getboolean" title="configparser.ConfigParser.getboolean"><code class="xref py py-meth docutils literal">getboolean()</code></a> を提供しています。このメソッドは大文字小文字を区別せず、 <code class="docutils literal">'yes'</code>/<code class="docutils literal">'no'</code>、<code class="docutils literal">'on'</code>/<code class="docutils literal">'off'</code>、<code class="docutils literal">'true'</code>/<code class="docutils literal">'false'</code>、<code class="docutils literal">'1'</code>/<code class="docutils literal">'0'</code> を真偽値として認識します <a class="footnote-reference" href="#id14" id="id3">[1]</a>。例えば:

<div class="highlight-python3"><div class="highlight"><pre>>>> topsecret.getboolean('ForwardX11')

False

>>> config['bitbucket.org'].getboolean('ForwardX11')

True

>>> config.getboolean('bitbucket.org', 'Compression')

True

</pre></div>

</div>

config parser では、 <a class="reference internal" href="#configparser.ConfigParser.getboolean" title="configparser.ConfigParser.getboolean"><code class="xref py py-meth docutils literal">getboolean()</code></a> 以外に <a class="reference internal" href="#configparser.ConfigParser.getint" title="configparser.ConfigParser.getint"><code class="xref py py-meth docutils literal">getint()</code></a> と <a class="reference internal" href="#configparser.ConfigParser.getfloat" title="configparser.ConfigParser.getfloat"><code class="xref py py-meth docutils literal">getfloat()</code></a> メソッドも提供されています。独自のコンバーターの登録、提供されたメソッドのカスタマイズもできます。 <a class="footnote-reference" href="#id14" id="id4">[1]</a>

</div>

辞書と同じように、セクションの <code class="xref py py-meth docutils literal">get()</code> メソッドは代替値を提供しています:

<div class="highlight-python3"><div class="highlight"><pre>>>> topsecret.get('Port')

'50022'

>>> topsecret.get('CompressionLevel')

'9'

>>> topsecret.get('Cipher')

>>> topsecret.get('Cipher', '3des-cbc')

'3des-cbc'

</pre></div>

</div>

デフォルト値は代替値よりも優先されることに注意してください。例えば上の例では、<code class="docutils literal">'CompressionLevel'</code> キーは <code class="docutils literal">'DEFAULT'</code> セクションにしか存在しません。その値を <code class="docutils literal">'topsecret.server.com'</code> から取得しようとした場合、代替値を指定しても常にデフォルト値を返します:

<div class="highlight-python3"><div class="highlight"><pre>>>> topsecret.get('CompressionLevel', '3')

'9'

</pre></div>

</div>

もう一つ注意すべき点は、パーサーレベルの(訳注: ConfigParserクラスの) <code class="xref py py-meth docutils literal">get()</code> メソッドは、後方互換性のために、カスタムのより複雑なインターフェースを提供します。このメソッドを使用する際には、フォールバック値はキーワード引数としてのみ指定できる <code class="docutils literal">fallback</code> 引数を介して提供されます:

<div class="highlight-python3"><div class="highlight"><pre>>>> config.get('bitbucket.org', 'monster',

... fallback='No such things as monsters')

'No such things as monsters'

</pre></div>

</div>

同様の <code class="docutils literal">fallback</code> 引数を、<a class="reference internal" href="#configparser.ConfigParser.getint" title="configparser.ConfigParser.getint"><code class="xref py py-meth docutils literal">getint()</code></a> 、 <a class="reference internal" href="#configparser.ConfigParser.getfloat" title="configparser.ConfigParser.getfloat"><code class="xref py py-meth docutils literal">getfloat()</code></a> と <a class="reference internal" href="#configparser.ConfigParser.getboolean" title="configparser.ConfigParser.getboolean"><code class="xref py py-meth docutils literal">getboolean()</code></a> メソッドでも使えます。例えば:

<div class="highlight-python3"><div class="highlight"><pre>>>> 'BatchMode' in topsecret

False

>>> topsecret.getboolean('BatchMode', fallback=True)

True

>>> config['DEFAULT']['BatchMode'] = 'no'

False

</pre></div>

</div>

<h2>14.2.4. サポートするINI ファイルの構造<a class="headerlink" href="#supported-ini-file-structure" title="このヘッドラインへのパーマリンク">¶</a></h2>

設定ファイルは複数のセクションから構成されます。セクションは、<code class="docutils literal">[section]</code> ヘッダに続いた、特定の文字列(デフォルトでは <code class="docutils literal">=</code> または <code class="docutils literal">:</code> <a class="footnote-reference" href="#id14" id="id6">[1]</a> )で区切られたキーと値のエントリです。デフォルトでは、セクション名は大文字と小文字を区別しますが、キーはそうではありません <a class="footnote-reference" href="#id14" id="id6">[1]</a>。キーと値、それぞれの先頭と末尾の空白は取り除かれます。値は省略することができ、その際でも、キーと値の区切り文字は残しておけます。値はまた、値の先頭の行より深くインデントされていれば、複数の行にまたがっても構いません。パーサーのモードによって、空白行は、複数行からなる値の一部として扱われるか、無視されます。

設定ファイルには先頭に特定の文字 (デフォルトでは <code class="docutils literal">#</code> および <code class="docutils literal">;</code> <a class="footnote-reference" href="#id14" id="id8">[1]</a>) をつけてコメントをつけることができます。コメントは、他の内容がない行に置くことができ、インデントされていても構いません。<a class="footnote-reference" href="#id14" id="id8">[1]</a>

例えば:

<div class="highlight-ini"><div class="highlight"><pre>[Simple Values]

key=value

spaces in keys=allowed

spaces in values=allowed as well

spaces around the delimiter = obviously

you can also use : to delimit keys from values

[All Values Are Strings]

values like this: 1000000

or this: 3.14159265359

are they treated as numbers? : no

integers, floats and booleans are held as: strings

can use the API to get converted values directly: true

[Multiline Values]

chorus: I'm a lumberjack, and I'm okay

I sleep all night and I work all day

[No Values]

key_without_value

empty string value here =

[You can use comments]

# like this

; or this

# By default only in an empty line.

# Inline comments can be harmful because they prevent users

# from using the delimiting characters as parts of values.

# That being said, this can be customized.

[Sections Can Be Indented]

can_values_be_as_well = True

does_that_mean_anything_special = False

purpose = formatting for readability

multiline_values = are

handled just fine as

long as they are indented

deeper than the first line

of a value

# Did I mention we can indent comments, too?

</pre></div>

</div>

コア機能に加えて、 <a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal">ConfigParser</code></a> は補間(interpolation, 内挿とも)をサポートします。これは <code class="docutils literal">get()</code> コールが値を返す前に、その値に対して前処理を行えることを意味します。

class <code class="descclassname">configparser.</code><code class="descname">BasicInterpolation</code><a class="headerlink" href="#configparser.BasicInterpolation" title="この定義へのパーマリンク">¶</a></dt>

<dd><a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal">ConfigParser</code></a> が使用するデフォルト実装です。値に、同じセクションか特別なデフォルトセクション中 <a class="footnote-reference" href="#id14" id="id9">[1]</a> の他の値を参照するフォーマット文字列を含めることができます。追加のデフォルト値を初期化時に提供できます。

例えば:

<div class="highlight-ini"><div class="highlight"><pre>[Paths]

home_dir: /Users

my_dir: %(home_dir)s/lumberjack

my_pictures: %(my_dir)s/Pictures

</pre></div>

</div>

上の例では、 interpolation に <code class="docutils literal">BasicInterpolation()</code> を設定した <a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal">ConfigParser</code></a> が <code class="docutils literal">%(home_dir)s</code> を <code class="docutils literal">home_dir</code> の値(このケースでは <code class="docutils literal">/Users</code> )として解決しています、その結果 <code class="docutils literal">%(my_dir)s</code> は <code class="docutils literal">/Users/lumberjack</code> になります。全ての補間は必要に応じて実行されるため、設定ファイル中で参照の連鎖をもつキーを特定の順序で記述する必要はありません。

<code class="docutils literal">interpolation</code> に <code class="docutils literal">None</code> を設定すれば、パーサーは単に <code class="docutils literal">my_pictures</code> の値として <code class="docutils literal">%(my_dir)s/Pictures</code> を返し、<code class="docutils literal">my_dir</code> の値として <code class="docutils literal">%(home_dir)s/lumberjack</code> を返します。

</dd></dl>

class <code class="descclassname">configparser.</code><code class="descname">ExtendedInterpolation</code><a class="headerlink" href="#configparser.ExtendedInterpolation" title="この定義へのパーマリンク">¶</a></dt>

<dd><code class="docutils literal">zc.buildout</code> で使用されるような、より高度な文法を実装した補間ハンドラの別の選択肢です。拡張された補間は、他のセクション中の値を示すのに <code class="docutils literal">${section:option}</code> と書けます。補間は複数のレベルに及べます、利便性のために、もし <code class="docutils literal">section:</code> の部分が省略されると、現在のセクションがデフォルト値となります(スペシャルセクション中のデフォルト値を使用することもできます)。

たとえば、上記の basic interpolation で指定した設定は、extended interpolation を使うと下記のようになります:

<div class="highlight-ini"><div class="highlight"><pre>[Paths]

home_dir: /Users

my_dir: ${home_dir}/lumberjack

my_pictures: ${my_dir}/Pictures

</pre></div>

</div>

他のセクションから値を持ってくることもできます:

<div class="highlight-ini"><div class="highlight"><pre>[Common]

home_dir: /Users

library_dir: /Library

system_dir: /System

macports_dir: /opt/local

[Frameworks]

Python: 3.2

path: ${Common:system_dir}/Library/Frameworks/

[Arthur]

nickname: Two Sheds

last_name: Jackson

my_dir: ${Common:home_dir}/twosheds

my_pictures: ${my_dir}/Pictures

python_dir: ${Frameworks:path}/Python/Versions/${Frameworks:Python}

</pre></div>

</div>

</dd></dl>

</div>

<h2>14.2.6. マップ型プロトコルアクセス<a class="headerlink" href="#mapping-protocol-access" title="このヘッドラインへのパーマリンク">¶</a></h2>

バージョン 3.2 で追加.

</div>

マップ型プロトコルアクセスは、カスタムオブジェクトを辞書であるかのように使うための機能の総称です。 <a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal">configparser</code></a> の場合、マップ型インタフェースの実装は <code class="docutils literal">parser['section']['option']</code> 表記を使います。

とくに、<code class="docutils literal">parser['section']</code> はパーサー内のそのセクションのデータへのプロキシを返します。つまり、値はコピーされるのではなく必要に応じてオリジナルのパーサーから取られます。さらに重要なことに、セクションのプロキシの値が変更されると、オリジナルのパーサー中の値が実際に変更されます。

<a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal">configparser</code></a> は可能な限り実際の辞書と近い振る舞いをします。マップ型インタフェースは <a class="reference internal" href="collections.abc.html#collections.abc.MutableMapping" title="collections.abc.MutableMapping"><code class="xref py py-class docutils literal">MutableMapping</code></a> を矛盾なく完成します。しかし、考慮するべき違いがいくつかあります:

<ul>

<li>デフォルトでは、セクション内の全てのキーは大文字小文字の区別なくアクセスできます <a class="footnote-reference" href="#id14" id="id10">[1]</a>。例えば、<code class="docutils literal">for option in parser["section"]</code> は <code class="docutils literal">optionxform</code> されたオプションキー名のみを yield します。つまり小文字のキーがデフォルトです。同時に、キー <code class="docutils literal">'a'</code> を含むセクションにおいて、どちらの式も <code class="docutils literal">True</code> を返します:

<div class="highlight-python3"><div class="highlight"><pre>"a" in parser["section"]

"A" in parser["section"]

</pre></div>

</div>

</li>

<li>全てのセクションは <code class="docutils literal">DEFAULTSECT</code> 値を持ち、すなわちセクションで <code class="docutils literal">.clear()</code> してもセクションは見た目上空になりません。これは、デフォルト値は (技術的にはそこにないので) セクションから削除できないためです。デフォルト値が上書きされた場合、それが削除されるとデフォルト値が再び見えるようになります。デフォルト値を削除しようとすると <code class="docutils literal">KeyError</code> が発生します。

</li>

<li><code class="docutils literal">DEFAULTSECT</code> はパーサーから取り除けません:

<li>削除しようとすると <code class="docutils literal">ValueError</code> が発生します。</li>

<li><code class="docutils literal">parser.clear()</code> はこれをそのまま残し、</li>

<li><code class="docutils literal">parser.popitem()</code> がこれを返すことはありません。</li>

</ul>

</li>

<li><code class="docutils literal">parser.get(section, option, **kwargs)</code> - 第二引数は代替値では ありません。ただし、セクションごとの <code class="docutils literal">get()</code> メソッドはマップ型プロトコルと旧式の configparser API の両方に互換です。

</li>

<li><code class="docutils literal">parser.items()</code> はマップ型プロトコルと互換です (DEFAULTSECT を含む section_name, section_proxy 対のリストを返します)。ただし、このメソッドは <code class="docutils literal">parser.items(section, raw, vars)</code> のようにして引数を与えることでも呼び出せます。後者の呼び出しは指定された <code class="docutils literal">section</code> の option, value 対のリストを、(<code class="docutils literal">raw=True</code> が与えられない限り) 全ての補間を展開して返します。

</li>

</ul>

マップ型プロトコルは、既存のレガシーな API の上に実装されているので、オリジナルのインタフェースを上書きする派生クラスもまたは期待どおりにはたらきます。

</div>

<h2>14.2.7. パーサーの振る舞いをカスタマイズする<a class="headerlink" href="#customizing-parser-behaviour" title="このヘッドラインへのパーマリンク">¶</a></h2>

INI フォーマットの変種は、それを使うアプリケーションの数と同じくらい多く存在します。 <a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal">configparser</code></a> は、可能な限り広い範囲の INI スタイルを集めた集合をサポートするために、非常に役立ちます。デフォルトの機能は主に歴史的背景によって決められたので、機能によってはカスタマイズしてお使いください。

特定の設定パーサーのはたらきを変える最も一般的な方法は <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal">__init__()</code></a> オプションを使うことです:

<ul>

<li>defaults, デフォルト値: <code class="docutils literal">None</code>

このオプションは最初に <code class="docutils literal">DEFAULT</code> セクションに加えられるキー-値の対の辞書を受け付けます。

ヒント: 特定のセクションにデフォルト値を指定したいなら、実際のファイルを読み込む前に <code class="xref py py-meth docutils literal">read_dict()</code> を使ってください。

</li>

<li>dict_type, デフォルト値: <a class="reference internal" href="collections.html#collections.OrderedDict" title="collections.OrderedDict"><code class="xref py py-class docutils literal">collections.OrderedDict</code></a>

このオプションはマップ型プロトコルの振る舞い方や書き込まれる設定ファイルの見た目に大きく影響します。デフォルトの順序付き辞書では、全てのセクションはパーサーに加えられた順に並びます。同じことがセクション内のオプションにも言えます。

セクションとオプションをライトバック時にソートするためなどに、別の辞書型も使えます。パフォーマンスの理由のために普通の辞書を使うこともできます。

注意: 一度の操作でキー-値の対を複数追加する方法もあります。そのような操作に普通の辞書を使うと、キーの並び順はランダムになります。例えば:

<div class="highlight-python3"><div class="highlight"><pre>>>> parser = configparser.ConfigParser()

>>> parser.read_dict({'section1': {'key1': 'value1',

... 'key2': 'value2',

... 'key3': 'value3'},

... 'section2': {'keyA': 'valueA',

... 'keyB': 'valueB',

... 'keyC': 'valueC'},

... 'section3': {'foo': 'x',

... 'bar': 'y',

... 'baz': 'z'}

... })

>>> parser.sections()

['section3', 'section2', 'section1']

>>> [option for option in parser['section3']]

['baz', 'foo', 'bar']

</pre></div>

</div>

このような操作には、順序付き辞書を使用する方がよいです:

<div class="highlight-python3"><div class="highlight"><pre>>>> from collections import OrderedDict

>>> parser = configparser.ConfigParser()

>>> parser.read_dict(

... OrderedDict((

... ('s1',

... OrderedDict((

... ('1', '2'),

... ('3', '4'),

... ('5', '6'),

... ))

... ),

... ('s2',

... OrderedDict((

... ('a', 'b'),

... ('c', 'd'),

... ('e', 'f'),

... ))

... ),

... ))

... )

>>> parser.sections()

['s1', 's2']

['1', '3', '5']

['b', 'd', 'f']

</pre></div>

</div>

</li>

<li>allow_no_value, デフォルト値: <code class="docutils literal">False</code>

一部の設定ファイルには値のない設定項目がありますが、それ以外は <code class="xref py py-mod docutils literal">ConfigParser</code> がサポートする文法に従います。コンストラクタの allow_no_value 引数で、そのような値を許可することができます。

<div class="highlight-python3"><div class="highlight"><pre>>>> import configparser

>>> sample_config = """

... [mysqld]

... user = mysql

... pid-file = /var/run/mysqld/mysqld.pid

... skip-external-locking

... old_passwords = 1

... skip-bdb

... # we don't need ACID today

... skip-innodb

... """

>>> config = configparser.ConfigParser(allow_no_value=True)

>>> config.read_string(sample_config)

>>> # Settings with values are treated as before:

>>> config["mysqld"]["user"]

'mysql'

>>> # Settings without values provide None:

>>> config["mysqld"]["skip-bdb"]

>>> # Settings which aren't specified still raise an error:

>>> config["mysqld"]["does-not-exist"]

Traceback (most recent call last):

...

KeyError: 'does-not-exist'

</pre></div>

</div>

</li>

<li>delimiters, デフォルト値: <code class="docutils literal">('=', ':')</code>

デリミタはセクション内でキーを値から区切る部分文字列です。行中で最初に現れた区切り部分文字列がデリミタと見なされます。つまり値にはデリミタを含めることができます (キーには含めることができません)。

<a class="reference internal" href="#configparser.ConfigParser.write" title="configparser.ConfigParser.write"><code class="xref py py-meth docutils literal">ConfigParser.write()</code></a> の space_around_delimiters 引数も参照してください。

</li>

<li>comment_prefixes, デフォルト値: <code class="docutils literal">('#', ';')</code>

</li>

<li>inline_comment_prefixes, デフォルト値: <code class="docutils literal">None</code>

コメント接頭辞は設定ファイル中で有効なコメントの開始を示す文字列です。comment_prefixes は他の内容がない行 (インデントは自由) にのみ使用でき、inline_comment_prefixes は任意の有効な値 (例えば、セクション名、オプション、空行も可能) の後に使えます。デフォルトではインラインコメントは無効化されていて、<code class="docutils literal">'#'</code> と <code class="docutils literal">';'</code> を行全体のコメントに使用します。

バージョン 3.2 で変更: 以前のバージョンの <a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal">configparser</code></a> の振る舞いは <code class="docutils literal">comment_prefixes=('#',';')</code> および <code class="docutils literal">inline_comment_prefixes=(';',)</code> に該当します。

</div>

設定パーサーはコメント接頭辞のエスケープをサポートしないので、inline_comment_prefixes はユーザーがコメント接頭辞として使われる文字を含むオプション値を指定するのを妨げる可能性があります。疑わしい場合には、inline_comment_prefixes を設定しないようにしてください。どのような状況でも、複数行にわたる値で、行の先頭にコメント接頭辞文字を保存する唯一の方法は、次の例のように接頭辞を補間することです:

<div class="highlight-python3"><div class="highlight"><pre>>>> from configparser import ConfigParser, ExtendedInterpolation

>>> parser = ConfigParser(interpolation=ExtendedInterpolation())

>>> # the default BasicInterpolation could be used as well

>>> parser.read_string("""

... [DEFAULT]

... hash = #

...

... [hashes]

... shebang =

... ${hash}!/usr/bin/env python

... ${hash} -*- coding: utf-8 -*-

...

... extensions =

... enabled_extension

... another_extension

... #disabled_by_comment

... yet_another_extension

...

... interpolation not necessary = if # is not at line start

... even in multiline values = line #1

... line #2

... line #3

... """)

>>> print(parser['hashes']['shebang'])

#!/usr/bin/env python

# -*- coding: utf-8 -*-

enabled_extension

another_extension

yet_another_extension

if # is not at line start

line #1

line #2

line #3

</pre></div>

</div>

</li>

<li>strict, デフォルト値: <code class="docutils literal">True</code>

<code class="docutils literal">True</code> に設定された場合、パーサーは単一のソースから (<code class="xref py py-meth docutils literal">read_file()</code>, <code class="xref py py-meth docutils literal">read_string()</code> または <code class="xref py py-meth docutils literal">read_dict()</code> を使って) 読み込むときにセクションやオプションの重複を許さなくなります。新しいアプリケーションには strict なパーサーを使うことが推奨されます。

バージョン 3.2 で変更: 以前のバージョンの <a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal">configparser</code></a> の振る舞いは <code class="docutils literal">strict=False</code> に該当します。

</div>

</li>

<li>empty_lines_in_values, デフォルト値: <code class="docutils literal">True</code>

設定パーサーでは、キーよりもその値を深くインデントするかぎり、複数行にまたがる値を使えます。デフォルトのパーサーはさらにその値の間に空行を置けます。同時に、キーは読みやすくするため任意にインデントできます。結果として、設定ファイルが大きく複雑になったとき、ユーザーがファイル構造を見失いやすいです。この例をご覧ください:

<div class="highlight-ini"><div class="highlight"><pre>[Section]

key = multiline

value with a gotcha

this = is still a part of the multiline value of 'key'

</pre></div>

</div>

これは特にプロポーショナルフォントを使ってファイルを編集しているユーザーにとって問題になることがあります。だから、アプリケーションの値に空行が必要ないなら、空行を認めないべきです。これによって空行で必ずキーが分かれます。上の例では、2 つのキー、<code class="docutils literal">key</code> および <code class="docutils literal">this</code> が作られます。

</li>

<li>default_section, デフォルト値: <code class="docutils literal">configparser.DEFAULTSECT</code> (すなわち: <code class="docutils literal">"DEFAULT"</code>)

他のセクションのデフォルト値や補間目的での特別なセクションを認める慣行はこのライブラリの明確なコンセプトの一つで、ユーザーは複雑で宣言的な設定を作成できます。このセクションは通常 <code class="docutils literal">"DEFAULT"</code> と呼ばれますが、任意の有効なセクション名を指すようにカスタマイズできます。典型的な値には <code class="docutils literal">"general"</code> や <code class="docutils literal">"common"</code> があります。与えられた名前はソースを読み込む際にデフォルトセクションを認識するのに使われ、設定をファイルに書き戻すときにも使われます。現在の値は <code class="docutils literal">parser_instance.default_section</code> 属性から取り出すことができ、実行時 (すなわちファイルを別のフォーマットに変換するとき) に変更することもできます。

</li>

<li>interpolation, デフォルト値: <code class="docutils literal">configparser.BasicInterpolation</code>

補間の振る舞いは、 interpolation 引数を通してカスタムハンドラを与えることでカスタマイズできます。 <code class="docutils literal">None</code> 引数を使うと補間を完全に無効にできます。 <code class="docutils literal">ExtendedInterpolation()</code> は、 <code class="docutils literal">zc.buildout</code> に影響を受けたより高度な補間を提供します。この話題に <a class="reference external" href="#interpolation-of-values">特化したドキュメントのセクション</a> をご覧ください。 <a class="reference internal" href="#configparser.RawConfigParser" title="configparser.RawConfigParser"><code class="xref py py-class docutils literal">RawConfigParser</code></a> のデフォルト値は <code class="docutils literal">None</code> です。

</li>

<li>converters, デフォルト値: 未設定

設定パーサーは、型変換を実行するオプションの値ゲッターを提供します。デフォルトでは、 <a class="reference internal" href="#configparser.ConfigParser.getint" title="configparser.ConfigParser.getint"><code class="xref py py-meth docutils literal">getint()</code></a>、 <a class="reference internal" href="#configparser.ConfigParser.getfloat" title="configparser.ConfigParser.getfloat"><code class="xref py py-meth docutils literal">getfloat()</code></a>、 <a class="reference internal" href="#configparser.ConfigParser.getboolean" title="configparser.ConfigParser.getboolean"><code class="xref py py-meth docutils literal">getboolean()</code></a> が実装されています。他のゲッターが必要な場合、ユーザーはそれらをサブクラスで定義するか、辞書を渡します。辞書を渡す場合、各キーはコンバーターの名前で、値は当該変換を実装する呼び出し可能オブジェクトです。例えば、 <code class="docutils literal">{'decimal': decimal.Decimal}</code> を渡すと、パーサーオブジェクトとすべてのセクションプロキシの両方に、 <code class="xref py py-meth docutils literal">getdecimal()</code> が追加されます。つまり、<code class="docutils literal">parser_instance.getdecimal('section', 'key', fallback=0)</code> と <code class="docutils literal">parser_instance['section'].getdecimal('key', 0)</code> の両方の方法で書くことができます。

コンバーターがパーサーの状態にアクセスする必要がある場合、設定パーサーサブクラスでメソッドとして実装することができます。このメソッドの名前が <code class="docutils literal">get</code> から始まる場合、すべてのセクションプロキシで、辞書と互換性のある形式で利用できます (上記の <code class="docutils literal">getdecimal()</code> の例を参照)。

</li>

</ul>

これらのパーサー引数のデフォルト値を上書きすれば、さらに進んだカスタマイズができます。デフォルトはクラスで定義されているので、派生クラスや属性の代入で上書きできます。

<code class="descclassname">configparser.</code><code class="descname">BOOLEAN_STATES</code><a class="headerlink" href="#configparser.BOOLEAN_STATES" title="この定義へのパーマリンク">¶</a></dt>

<dd>デフォルトでは、 <a class="reference internal" href="#configparser.ConfigParser.getboolean" title="configparser.ConfigParser.getboolean"><code class="xref py py-meth docutils literal">getboolean()</code></a> を使うことで、設定パーサーは以下の値を <code class="docutils literal">True</code> と見なします: <code class="docutils literal">'1'</code>, <code class="docutils literal">'yes'</code>, <code class="docutils literal">'true'</code>, <code class="docutils literal">'on'</code> 。以下の値を <code class="docutils literal">False</code> と見なします: <code class="docutils literal">'0'</code>, <code class="docutils literal">'no'</code>, <code class="docutils literal">'false'</code>, <code class="docutils literal">'off'</code> 。文字列と対応するブール値のカスタム辞書を指定することでこれを上書きできます。たとえば:

<div class="highlight-python3"><div class="highlight"><pre>>>> custom = configparser.ConfigParser()

>>> custom['section1'] = {'funky': 'nope'}

>>> custom['section1'].getboolean('funky')

Traceback (most recent call last):

...

ValueError: Not a boolean: nope

>>> custom.BOOLEAN_STATES = {'sure': True, 'nope': False}

False

</pre></div>

</div>

ほかの典型的なブール値ペアには <code class="docutils literal">accept</code>/<code class="docutils literal">reject</code> や <code class="docutils literal">enabled</code>/<code class="docutils literal">disabled</code> などがあります。

</dd></dl>

<code class="descclassname">configparser.</code><code class="descname">optionxform</code>(option)<a class="headerlink" href="#configparser.optionxform" title="この定義へのパーマリンク">¶</a></dt>

<dd>このメソッドは読み込み、取得、設定操作のたびにオプション名を変換します。デフォルトでは名前を小文字に変換します。従って設定ファイルが書き込まれるとき、すべてのキーは小文字になります。それがふさわしくなければ、このメソッドを上書きしてください。例えば:

<div class="highlight-python3"><div class="highlight"><pre>>>> config = """

... [Section1]

... Key = Value

...

... [Section2]

... AnotherKey = Value

... """

>>> typical = configparser.ConfigParser()

>>> typical.read_string(config)

>>> list(typical['Section1'].keys())

['key']

>>> list(typical['Section2'].keys())

['anotherkey']

>>> custom = configparser.RawConfigParser()

>>> custom.optionxform = lambda option: option

>>> custom.read_string(config)

>>> list(custom['Section1'].keys())

['Key']

>>> list(custom['Section2'].keys())

['AnotherKey']

</pre></div>

</div>

</dd></dl>

<code class="descclassname">configparser.</code><code class="descname">SECTCRE</code><a class="headerlink" href="#configparser.SECTCRE" title="この定義へのパーマリンク">¶</a></dt>

<dd>セクションヘッダを解析するのに使われる、コンパイルされた正規表現です。デフォルトでは <code class="docutils literal">[section]</code> が <code class="docutils literal">"section"</code> という名前にマッチします。空白はセクション名の一部と見なされるので、<code class="docutils literal">[  larch  ]</code> は <code class="docutils literal">"  larch  "</code> という名のセクションとして読み込まれます。これがふさわしくない場合、このメソッドを上書きしてください。例えば:

<div class="highlight-python3"><div class="highlight"><pre>>>> config = """

... [Section 1]

... option = value

...

... [ Section 2 ]

... another = val

... """

>>> typical = ConfigParser()

>>> typical.read_string(config)

>>> typical.sections()

['Section 1', ' Section 2 ']

>>> custom = ConfigParser()

>>> custom.SECTCRE = re.compile(r"\[ *(?P<header>[^]]+?) *\]")

>>> custom.read_string(config)

>>> custom.sections()

['Section 1', 'Section 2']

</pre></div>

</div>

注釈

ConfigParser オブジェクトはオプション行の認識に <code class="docutils literal">OPTCRE</code> 属性も使いますが、これを上書きすることは推奨されません。上書きするとコンストラクタオプション allow_no_value および delimiters に干渉します。

</div>

</dd></dl>

</div>

<h2>14.2.8. レガシーな API の例<a class="headerlink" href="#legacy-api-examples" title="このヘッドラインへのパーマリンク">¶</a></h2>

主に後方互換性問題の理由から、 <a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal">configparser</code></a> は <code class="docutils literal">get</code>/<code class="docutils literal">set</code> メソッドを明示するレガシーな API も提供します。メソッドを以下に示すように使うこともできますが、新しいプロジェクトではマップ型プロトコルでアクセスするのが望ましいです。レガシーな API は時折高度で、低レベルで、まったく直感的ではありません。

設定ファイルを書き出す例:

<div class="highlight-python3"><div class="highlight"><pre>import configparser

config = configparser.RawConfigParser()

# Please note that using RawConfigParser's set functions, you can assign

# non-string values to keys internally, but will receive an error when

# attempting to write to a file or when you get it in non-raw mode. Setting

# values using the mapping protocol or ConfigParser's set() does not allow

# such assignments to take place.

config.add_section('Section1')

config.set('Section1', 'an_int', '15')

config.set('Section1', 'a_bool', 'true')

config.set('Section1', 'a_float', '3.1415')

config.set('Section1', 'baz', 'fun')

config.set('Section1', 'bar', 'Python')

config.set('Section1', 'foo', '%(bar)s is %(baz)s!')

# Writing our configuration file to 'example.cfg'

with open('example.cfg', 'w') as configfile:

config.write(configfile)

</pre></div>

</div>

設定ファイルを読み込む例:

<div class="highlight-python3"><div class="highlight"><pre>import configparser

config = configparser.RawConfigParser()

config.read('example.cfg')

# getfloat() raises an exception if the value is not a float

# getint() and getboolean() also do this for their respective types

a_float = config.getfloat('Section1', 'a_float')

an_int = config.getint('Section1', 'an_int')

print(a_float + an_int)

# Notice that the next output does not interpolate '%(bar)s' or '%(baz)s'.

# This is because we are using a RawConfigParser().

if config.getboolean('Section1', 'a_bool'):

print(config.get('Section1', 'foo'))

</pre></div>

</div>

補間するには、 <a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal">ConfigParser</code></a> を使ってください:

<div class="highlight-python3"><div class="highlight"><pre>import configparser

cfg = configparser.ConfigParser()

cfg.read('example.cfg')

# Set the optional *raw* argument of get() to True if you wish to disable

# interpolation in a single get operation.

print(cfg.get('Section1', 'foo', raw=False)) # -> "Python is fun!"

print(cfg.get('Section1', 'foo', raw=True)) # -> "%(bar)s is %(baz)s!"

# The optional *vars* argument is a dict with members that will take

# precedence in interpolation.

print(cfg.get('Section1', 'foo', vars={'bar': 'Documentation',

'baz': 'evil'}))

# The optional *fallback* argument can be used to provide a fallback value

# -> "Python is fun!"

print(cfg.get('Section1', 'foo', fallback='Monty is not.'))

# -> "Python is fun!"

print(cfg.get('Section1', 'monster', fallback='No such things as monsters.'))

# -> "No such things as monsters."

# A bare print(cfg.get('Section1', 'monster')) would raise NoOptionError

# but we can also use:

print(cfg.get('Section1', 'monster', fallback=None))

# -> None

</pre></div>

</div>

どちらの型の ConfigParsers でもデフォルト値が利用できます。使われているオプションがどこにも定義されていなければ、そのデフォルト値が補間に使われます。

<div class="highlight-python3"><div class="highlight"><pre>import configparser

# New instance with 'bar' and 'baz' defaulting to 'Life' and 'hard' each

config = configparser.ConfigParser({'bar': 'Life', 'baz': 'hard'})

config.read('example.cfg')

config.remove_option('Section1', 'bar')

</pre></div>

</div>

<h2>14.2.9. ConfigParser オブジェクト<a class="headerlink" href="#configparser-objects" title="このヘッドラインへのパーマリンク">¶</a></h2>

class <code class="descclassname">configparser.</code><code class="descname">ConfigParser</code>(defaults=None, dict_type=collections.OrderedDict, allow_no_value=False, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=configparser.DEFAULTSECT, interpolation=BasicInterpolation(), converters={})<a class="headerlink" href="#configparser.ConfigParser" title="この定義へのパーマリンク">¶</a></dt>

<dd>主要な設定パーサーです。defaults が与えられれば、その辞書の持つ初期値で初期化されます。dict_type が与えられれば、それがセクションの一覧、セクション中のオプション、およびデフォルト値の辞書オブジェクトを作成するのに使われます。

delimiters が与えられた場合、キーと値を分割する部分文字列の組み合わせとして使われます。comment_prefixes が与えられた場合、他の内容がない行のコメントに接頭する部分文字列の組み合わせとして使われます。コメントはインデントできます。inline_comment_prefixes が与えられた場合、非空行のコメントに接頭する部分文字列としての組み合わせとして使われます。

strict が <code class="docutils literal">True</code> (デフォルト) であれば、パーサーは単一のソース (ファイル、文字列、辞書) 中にセクションやオプションの重複を認めず、 <a class="reference internal" href="#configparser.DuplicateSectionError" title="configparser.DuplicateSectionError"><code class="xref py py-exc docutils literal">DuplicateSectionError</code></a> や <a class="reference internal" href="#configparser.DuplicateOptionError" title="configparser.DuplicateOptionError"><code class="xref py py-exc docutils literal">DuplicateOptionError</code></a> を送出します。 empty_lines_in_values が <code class="docutils literal">False</code> (デフォルト: <code class="docutils literal">True</code>) なら、空行はそれぞれオプションの終わりを示します。 allow_no_value が <code class="docutils literal">True</code> (デフォルト: <code class="docutils literal">False</code>) なら、値のないオプションが受け付けられます。そのオプションの値は <code class="docutils literal">None</code> となり、後端のデリミタを除いてシリアル化されます。

default_section が与えられた場合、他のセクションへのデフォルト値や補間のためのデフォルト値を保持する特別なセクションの名前を指定します (通常は <code class="docutils literal">"DEFAULT"</code> という名前です)。この値は実行時に <code class="docutils literal">default_section</code> インスタンス属性を使って取得や変更ができます。

補間の動作は、 interpolation 引数を通してカスタムハンドラを与えることでカスタマイズできます。 <code class="docutils literal">None</code> 引数を使うと補間を完全に無効にできます。 <code class="docutils literal">ExtendedInterpolation()</code> は、 <code class="docutils literal">zc.buildout</code> に影響を受けたより高度な補間を提供します。この件に <a class="reference external" href="#interpolation-of-values">特化したドキュメントのセクション</a> を参照してください。

補間に使われるすべてのオプション名は、他のオプション名参照と同様に、 <a class="reference internal" href="#configparser.optionxform" title="configparser.optionxform"><code class="xref py py-meth docutils literal">optionxform()</code></a> メソッドを通して渡されます。例えば、 <a class="reference internal" href="#configparser.optionxform" title="configparser.optionxform"><code class="xref py py-meth docutils literal">optionxform()</code></a> のデフォルトの実装を使うと、値 <code class="docutils literal">foo %(bar)s</code> と <code class="docutils literal">foo %(BAR)s</code> は等しくなります。

converters が与えられた場合、各キーが型コンバーターの名前を表し、各値が文字列から目的のデータ型への変換を実装する呼び出し可能オブジェクトです。各コンバーターは、自身の対応する <code class="xref py py-meth docutils literal">get*()</code> メソッドをパーサーオブジェクトとセクションプロキシで取得します。

バージョン 3.1 で変更: デフォルトの dict_type は <a class="reference internal" href="collections.html#collections.OrderedDict" title="collections.OrderedDict"><code class="xref py py-class docutils literal">collections.OrderedDict</code></a> です。

</div>

バージョン 3.2 で変更: allow_no_value, delimiters, comment_prefixes, strict, empty_lines_in_values, default_section および interpolation が追加されました。

</div>

バージョン 3.5 で変更: converters 引数が追加されました。

</div>

<code class="descname">defaults</code>()<a class="headerlink" href="#configparser.ConfigParser.defaults" title="この定義へのパーマリンク">¶</a></dt>

<dd>インスタンス全体で使われるデフォルト値の辞書を返します。

</dd></dl>

<code class="descname">sections</code>()<a class="headerlink" href="#configparser.ConfigParser.sections" title="この定義へのパーマリンク">¶</a></dt>

<dd>利用できるセクションのリストを返します。default section はリストに含まれません。

</dd></dl>

<code class="descname">add_section</code>(section)<a class="headerlink" href="#configparser.ConfigParser.add_section" title="この定義へのパーマリンク">¶</a></dt>

<dd>section という名のセクションをインスタンスに追加します。与えられた名前のセクション名がすでに存在したら、 <a class="reference internal" href="#configparser.DuplicateSectionError" title="configparser.DuplicateSectionError"><code class="xref py py-exc docutils literal">DuplicateSectionError</code></a> が送出されます。 default section 名が渡されたら、 <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal">ValueError</code></a> が送出されます。セクションの名前は文字列でなければなりません。そうでなければ、 <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal">TypeError</code></a> が送出されます。

バージョン 3.2 で変更: 文字列でないセクション名は <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal">TypeError</code></a> を送出します。

</div>

</dd></dl>

<code class="descname">has_section</code>(section)<a class="headerlink" href="#configparser.ConfigParser.has_section" title="この定義へのパーマリンク">¶</a></dt>

<dd>指名された section が設定中に存在するかを示します。default section は認識されません。

</dd></dl>

<code class="descname">options</code>(section)<a class="headerlink" href="#configparser.ConfigParser.options" title="この定義へのパーマリンク">¶</a></dt>

<dd>指定された section 中で利用できるオプションのリストを返します。

</dd></dl>

<code class="descname">has_option</code>(section, option)<a class="headerlink" href="#configparser.ConfigParser.has_option" title="この定義へのパーマリンク">¶</a></dt>

<dd>与えられた section が存在し、与えられた option を含む場合、 <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal">True</code></a> を返します。それ以外の場合には、 <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal">False</code></a> を返します。指定された section が <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a> または空文字列の場合、 DEFAULT が仮定されます。

</dd></dl>

<code class="descname">read</code>(filenames, encoding=None)<a class="headerlink" href="#configparser.ConfigParser.read" title="この定義へのパーマリンク">¶</a></dt>

<dd>ファイル名のリストを読み込んでパースしようと試みます。正常にパースできたファイル名のリストを返します。

もし filenames が文字列か <a class="reference internal" href="../glossary.html#term-path-like-object">path-like object</a> なら、この引数は1つのファイル名として扱われます。 filenames 中に開けないファイルがある場合、そのファイルは無視されます。この挙動は、設定ファイルが置かれる可能性のある場所(例えば、カレントディレクトリ、ホームディレクトリ、システム全体の設定を行うディレクトリ)のリストを指定して、リストの中で存在する全ての設定ファイルを読むことを想定して設計されています。

どの設定ファイルも存在しなかった場合、 <a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal">ConfigParser</code></a> のインスタンスは空のデータセットを持ちます。初期値の設定ファイルを先に読み込んでおく必要があるアプリケーションでは、オプションのファイルを読み込むために <a class="reference internal" href="#configparser.ConfigParser.read" title="configparser.ConfigParser.read"><code class="xref py py-meth docutils literal">read()</code></a> を呼ぶ前に、まず <a class="reference internal" href="#configparser.ConfigParser.read_file" title="configparser.ConfigParser.read_file"><code class="xref py py-meth docutils literal">read_file()</code></a> を用いて必要なファイルを読み込んでください:

<div class="highlight-python3"><div class="highlight"><pre>import configparser, os

config = configparser.ConfigParser()

config.read_file(open('defaults.cfg'))

config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')],

encoding='cp1250')

</pre></div>

</div>

バージョン 3.2 で追加: encoding 引数。以前は、すべてのファイルが <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal">open()</code></a> のデフォルトエンコーディングを使って読まれていました。

</div>

バージョン 3.6.1 で追加: filenames 引数が <a class="reference internal" href="../glossary.html#term-path-like-object">path-like object</a> を受け入れるようになりました。

</div>

</dd></dl>

<code class="descname">read_file</code>(f, source=None)<a class="headerlink" href="#configparser.ConfigParser.read_file" title="この定義へのパーマリンク">¶</a></dt>

<dd>設定データを f から読み込んで解析します。f は Unicode 文字列を yield するイテラブル (例えばテキストモードで開かれたファイル) です。

オプションの引数 source は読み込まれるファイルの名前を指定します。与えられず、 f に <code class="xref py py-attr docutils literal">name</code> 属性があれば、それが source として使われます。デフォルトは <code class="docutils literal">'<???>'</code> です。

バージョン 3.2 で追加: <a class="reference internal" href="#configparser.ConfigParser.readfp" title="configparser.ConfigParser.readfp"><code class="xref py py-meth docutils literal">readfp()</code></a> を置き換えます。

</div>

</dd></dl>

<code class="descname">read_string</code>(string, source='<string>')<a class="headerlink" href="#configparser.ConfigParser.read_string" title="この定義へのパーマリンク">¶</a></dt>

<dd>設定データを文字列から解析します。

オプションの引数 source はコンテキストにおける渡された文字列の名前を指定します。与えられなければ、<code class="docutils literal">'<string>'</code> が使われます。これは一般にファイルシステムパスや URL にします。

バージョン 3.2 で追加.

</div>

</dd></dl>

<code class="descname">read_dict</code>(dictionary, source='<dict>')<a class="headerlink" href="#configparser.ConfigParser.read_dict" title="この定義へのパーマリンク">¶</a></dt>

<dd>辞書的な <code class="docutils literal">items()</code> メソッドを提供する任意のオブジェクトから設定を読み込みます。キーはセクション名で、値はそのセクションに現れるキーと値をもつ辞書です。使われた辞書型が順序を保存するなら、セクションおよびそのキーは順に加えられます。値は自動で文字列に変換されます。

オプションの引数 source はコンテキストにおける渡された辞書の名前を指定します。与えられなければ、<code class="docutils literal"><dict></code> が使われます。

このメソッドを使ってパーサー間で状態をコピーできます。

バージョン 3.2 で追加.

</div>

</dd></dl>

<code class="descname">get</code>(section, option, *, raw=False, vars=None[, fallback])<a class="headerlink" href="#configparser.ConfigParser.get" title="この定義へのパーマリンク">¶</a></dt>

<dd>指名された section の option の値を取得します。vars が提供されるなら、それは辞書でなければならず、(与えられたなら) vars, section, DEFAULTSECT 内からこの順で option が探索されます。fallback の値として <code class="docutils literal">None</code> を与えられます。

raw が真でない時には、全ての <code class="docutils literal">'%'</code> 置換は展開されてから返されます。置換後の値はオプションと同じ順序で探されます。

バージョン 3.2 で変更: 引数 raw, vars および fallback は、(特にマッピングプロトコルを使用するときに) ユーザーが第 3 引数を fallback フォールバックとして使おうとしないように、キーワード専用となりました。

</div>

</dd></dl>

<code class="descname">getint</code>(section, option, *, raw=False, vars=None[, fallback])<a class="headerlink" href="#configparser.ConfigParser.getint" title="この定義へのパーマリンク">¶</a></dt>

<dd>指定された section 中の option を整数に型強制する補助メソッドです。 raw, vars および fallback の説明は <a class="reference internal" href="#configparser.ConfigParser.get" title="configparser.ConfigParser.get"><code class="xref py py-meth docutils literal">get()</code></a> を参照してください。

</dd></dl>

<code class="descname">getfloat</code>(section, option, *, raw=False, vars=None[, fallback])<a class="headerlink" href="#configparser.ConfigParser.getfloat" title="この定義へのパーマリンク">¶</a></dt>

<dd>指定された section 中の option を浮動小数点数に型強制する補助メソッドです。 raw, vars および fallback の説明は <a class="reference internal" href="#configparser.ConfigParser.get" title="configparser.ConfigParser.get"><code class="xref py py-meth docutils literal">get()</code></a> を参照してください。

</dd></dl>

<code class="descname">getboolean</code>(section, option, *, raw=False, vars=None[, fallback])<a class="headerlink" href="#configparser.ConfigParser.getboolean" title="この定義へのパーマリンク">¶</a></dt>

<dd>指定された section 中の option をブール値に型強制する補助メソッドです。なお、このオプションで受け付けられる値はこのメソッドが <code class="docutils literal">True</code> を返す <code class="docutils literal">'1'</code>, <code class="docutils literal">'yes'</code>, <code class="docutils literal">'true'</code>, および <code class="docutils literal">'on'</code>,と、このメソッドが <code class="docutils literal">False</code> を返す <code class="docutils literal">'0'</code>, <code class="docutils literal">'no'</code>, <code class="docutils literal">'false'</code>, and <code class="docutils literal">'off'</code> です。その他のいかなる値も <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal">ValueError</code></a> を送出します。 raw, vars および fallback の説明は <a class="reference internal" href="#configparser.ConfigParser.get" title="configparser.ConfigParser.get"><code class="xref py py-meth docutils literal">get()</code></a> を参照してください。

</dd></dl>

<code class="descname">items</code>(raw=False, vars=None)<a class="headerlink" href="#configparser.ConfigParser.items" title="この定義へのパーマリンク">¶</a></dt>

<dt>

<code class="descname">items</code>(section, raw=False, vars=None)</dt>

<dd>section が与えられなければ、DEFAULTSECT を含めた section_name, section_proxy の対のリストを返します。

与えられれば、与えられた section 中のオプションの name, value の対のリストを返します。オプションの引数は <a class="reference internal" href="#configparser.ConfigParser.get" title="configparser.ConfigParser.get"><code class="xref py py-meth docutils literal">get()</code></a> メソッドに与えるものと同じ意味を持ちます。

バージョン 3.2 で変更: Items present in vars no longer appear in the result. The previous

behaviour mixed actual parser options with variables provided for

interpolation.

</div>

</dd></dl>

<code class="descname">set</code>(section, option, value)<a class="headerlink" href="#configparser.ConfigParser.set" title="この定義へのパーマリンク">¶</a></dt>

<dd>与えられたセクションが存在すれば、与えられたオプションを指定された値に設定します。そうでなければ <a class="reference internal" href="#configparser.NoSectionError" title="configparser.NoSectionError"><code class="xref py py-exc docutils literal">NoSectionError</code></a> を送出します。 option および value は文字列でなければなりません。そうでなければ <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal">TypeError</code></a> が送出されます。

</dd></dl>

<code class="descname">write</code>(fileobject, space_around_delimiters=True)<a class="headerlink" href="#configparser.ConfigParser.write" title="この定義へのパーマリンク">¶</a></dt>

<dd>設定の表現を指定された <a class="reference internal" href="../glossary.html#term-file-object">file object</a> に書き込みます。 fileobject は (文字列を受け付ける) テキストモードで開かれていなければなりません。この表現は後で <a class="reference internal" href="#configparser.ConfigParser.read" title="configparser.ConfigParser.read"><code class="xref py py-meth docutils literal">read()</code></a> を呼び出すことでパースできます。 space_around_delimiters が真なら、キーと値の間のデリミタはスペースで囲まれます。

</dd></dl>

<code class="descname">remove_option</code>(section, option)<a class="headerlink" href="#configparser.ConfigParser.remove_option" title="この定義へのパーマリンク">¶</a></dt>

<dd>指定された option を指定された section から削除します。セクションが存在しなければ、 <a class="reference internal" href="#configparser.NoSectionError" title="configparser.NoSectionError"><code class="xref py py-exc docutils literal">NoSectionError</code></a> を送出します。オプションが存在して削除されれば、 <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal">True</code></a> を返します。そうでなければ <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal">False</code></a> を返します。

</dd></dl>

<code class="descname">remove_section</code>(section)<a class="headerlink" href="#configparser.ConfigParser.remove_section" title="この定義へのパーマリンク">¶</a></dt>

<dd>指定された section を設定から削除します。セクションが実際に存在すれば、<code class="docutils literal">True</code> を返します。そうでなければ <code class="docutils literal">False</code> を返します。

</dd></dl>

<code class="descname">optionxform</code>(option)<a class="headerlink" href="#configparser.ConfigParser.optionxform" title="この定義へのパーマリンク">¶</a></dt>

<dd>入力ファイルに現れた、またはクライアントコードで渡されたオプション名 option を内部構造で実際に使われる形式に変換します。デフォルトの実装では option の小文字版を返します。派生クラスでこれを上書きするか、クライアントコードでインスタンス上のこの名前の属性を設定して、この動作に影響を与えることができます。

このメソッドを使うためにパーサーを派生クラス化させる必要はなく、インスタンス上で、これを文字列引数をとって文字列を返す関数に設定できます。例えば、これを <code class="docutils literal">str</code> に設定すると、オプション名に大文字小文字の区別をつけられます:

<div class="highlight-python3"><div class="highlight"><pre>cfgparser = ConfigParser()

cfgparser.optionxform = str

</pre></div>

</div>

なお、設定ファイルを読み込むとき、オプション名の周りの空白は <a class="reference internal" href="#configparser.optionxform" title="configparser.optionxform"><code class="xref py py-meth docutils literal">optionxform()</code></a> が呼び出される前に取り除かれます。

</dd></dl>

<code class="descname">readfp</code>(fp, filename=None)<a class="headerlink" href="#configparser.ConfigParser.readfp" title="この定義へのパーマリンク">¶</a></dt>

バージョン 3.2 で撤廃: 代わりに <a class="reference internal" href="#configparser.ConfigParser.read_file" title="configparser.ConfigParser.read_file"><code class="xref py py-meth docutils literal">read_file()</code></a> を使ってください。

</div>

バージョン 3.2 で変更: <a class="reference internal" href="#configparser.ConfigParser.readfp" title="configparser.ConfigParser.readfp"><code class="xref py py-meth docutils literal">readfp()</code></a> は <code class="docutils literal">fp.readline()</code> を呼び出す代わりに fp をイテレートするようになりました。

</div>

<a class="reference internal" href="#configparser.ConfigParser.readfp" title="configparser.ConfigParser.readfp"><code class="xref py py-meth docutils literal">readfp()</code></a> をイテレーションをサポートしない引数で呼び出す既存のコードには、ファイル的なオブジェクトまわりのラッパーとして以下のジェネレーターが使えます:

<div class="highlight-python3"><div class="highlight"><pre>def readline_generator(fp):

line = fp.readline()

while line:

yield line

line = fp.readline()

</pre></div>

</div>

<code class="docutils literal">parser.readfp(fp)</code> の代わりに <code class="docutils literal">parser.read_file(readline_generator(fp))</code> を使ってください。

</dd></dl>

<code class="descclassname">configparser.</code><code class="descname">MAX_INTERPOLATION_DEPTH</code><a class="headerlink" href="#configparser.MAX_INTERPOLATION_DEPTH" title="この定義へのパーマリンク">¶</a></dt>

<dd><code class="xref py py-meth docutils literal">get()</code> の raw が偽であるときの再帰的な補間の最大の深さです。これはデフォルトの interpolation を使うときのみ関係します。

</dd></dl>

</div>

<h2>14.2.10. RawConfigParser オブジェクト<a class="headerlink" href="#rawconfigparser-objects" title="このヘッドラインへのパーマリンク">¶</a></h2>

class <code class="descclassname">configparser.</code><code class="descname">RawConfigParser</code>(defaults=None, dict_type=collections.OrderedDict, allow_no_value=False, *, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=configparser.DEFAULTSECT[, interpolation])<a class="headerlink" href="#configparser.RawConfigParser" title="この定義へのパーマリンク">¶</a></dt>

<dd>補間や不安全な <code class="docutils literal">add_section</code> および <code class="docutils literal">set</code> メソッドがデフォルトで無効化されている、レガシーな <a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal">ConfigParser</code></a> の別型です。

注釈

代わりに内部に保存する値の型を検査する <a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal">ConfigParser</code></a> を使うことを検討してください。補間を望まない場合、 <code class="docutils literal">ConfigParser(interpolation=None)</code> を使用できます。

</div>

<code class="descname">add_section</code>(section)<a class="headerlink" href="#configparser.RawConfigParser.add_section" title="この定義へのパーマリンク">¶</a></dt>

<dd>インスタンスに section という名のセクションを追加します。与えられた名前のセクションがすでに存在すれば、 <a class="reference internal" href="#configparser.DuplicateSectionError" title="configparser.DuplicateSectionError"><code class="xref py py-exc docutils literal">DuplicateSectionError</code></a> が送出されます。 default section 名が渡されると、 <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal">ValueError</code></a> が送出されます。

section の型は検査されないため、ユーザーは非文字列の名前付きセクションを作ることができます。この振る舞いはサポートされておらず、内部エラーを起こす可能性があります。

</dd></dl>

<code class="descname">set</code>(section, option, value)<a class="headerlink" href="#configparser.RawConfigParser.set" title="この定義へのパーマリンク">¶</a></dt>

<dd>与えられたセクションが存在していれば、オプションを指定された値に設定します。セクションが存在しなければ <a class="reference internal" href="#configparser.NoSectionError" title="configparser.NoSectionError"><code class="xref py py-exc docutils literal">NoSectionError</code></a> を発生させます。 <a class="reference internal" href="#configparser.RawConfigParser" title="configparser.RawConfigParser"><code class="xref py py-class docutils literal">RawConfigParser</code></a> (あるいは raw パラメータをセットした <a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal">ConfigParser</code></a>) を文字列型でない値の 内部的な 格納場所として使うことは可能ですが、すべての機能 (置換やファイルへの出力を含む) がサポートされるのは文字列を値として使った場合だけです。

ユーザーは、このメソッドを使って非文字列の値をキーに代入できます。この振る舞いはサポートされておらず、非rawモードでの値の取得や、ファイルへの書き出しを試みた際にエラーの原因となりえます。このような代入を許さない マッピングプロトコルAPIを使用してください。

</dd></dl>

</div>

exception <code class="descclassname">configparser.</code><code class="descname">Error</code><a class="headerlink" href="#configparser.Error" title="この定義へのパーマリンク">¶</a></dt>

<dd>他の全ての <a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal">configparser</code></a> 例外の基底クラスです。

</dd></dl>

exception <code class="descclassname">configparser.</code><code class="descname">NoSectionError</code><a class="headerlink" href="#configparser.NoSectionError" title="この定義へのパーマリンク">¶</a></dt>

<dd>指定したセクションが見つからなかった時に起きる例外です。

</dd></dl>

exception <code class="descclassname">configparser.</code><code class="descname">DuplicateSectionError</code><a class="headerlink" href="#configparser.DuplicateSectionError" title="この定義へのパーマリンク">¶</a></dt>

<dd><code class="xref py py-meth docutils literal">add_section()</code> がすでに存在するセクションの名前で呼び出された場合や、strict なパーサーで単一の入力ファイル、文字列、辞書中に同じセクションが複数回現れたときに送出される例外です。

バージョン 3.2 で追加: オプションの <code class="docutils literal">source</code> と <code class="docutils literal">lineno</code> が属性および <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal">__init__()</code></a> への引数として加えられました。

</div>

</dd></dl>

exception <code class="descclassname">configparser.</code><code class="descname">DuplicateOptionError</code><a class="headerlink" href="#configparser.DuplicateOptionError" title="この定義へのパーマリンク">¶</a></dt>

<dd>strict なパーサーで、単一の入力ファイル、文字列、辞書中に同じオプションが複数回現れたときに送出される例外です。これはミススペルや大文字小文字の区別に関係するエラー、例えば辞書の二つのキーが同じ大文字小文字の区別のない設定キーを表すこと、を捕捉します。

</dd></dl>

exception <code class="descclassname">configparser.</code><code class="descname">NoOptionError</code><a class="headerlink" href="#configparser.NoOptionError" title="この定義へのパーマリンク">¶</a></dt>

<dd>指定されたオプションが指定されたセクションに見つからないときに送出される例外です。

</dd></dl>

View remainder of file in raw view

FilesExpand file tree

configparser.html

Latest commit

History

configparser.html

File metadata and controls