~dkuhlman/python-training-materials/Materials

<h1>28.8. <a class="reference internal" href="#module-abc" title="abc: Abstract base classes according to PEP 3119."><code class="xref py py-mod docutils literal">abc</code></a> — Abstract Base Classes<a class="headerlink" href="#module-abc" title="Permalink to this headline">¶</a></h1>

New in version 2.6.

</div>

Source code: <a class="reference external" href="https://hg.python.org/cpython/file/2.7/Lib/abc.py">Lib/abc.py</a>

This module provides the infrastructure for defining <a class="reference internal" href="../glossary.html#term-abstract-base-class">abstract base

classes</a> (ABCs) in Python, as outlined in <a class="pep reference external" href="https://www.python.org/dev/peps/pep-3119">PEP 3119</a>; see the PEP for why this

was added to Python. (See also <a class="pep reference external" href="https://www.python.org/dev/peps/pep-3141">PEP 3141</a> and the <a class="reference internal" href="numbers.html#module-numbers" title="numbers: Numeric abstract base classes (Complex, Real, Integral, etc.)."><code class="xref py py-mod docutils literal">numbers</code></a> module

regarding a type hierarchy for numbers based on ABCs.)

The <a class="reference internal" href="collections.html#module-collections" title="collections: High-performance datatypes"><code class="xref py py-mod docutils literal">collections</code></a> module has some concrete classes that derive from

ABCs; these can, of course, be further derived. In addition the

<a class="reference internal" href="collections.html#module-collections" title="collections: High-performance datatypes"><code class="xref py py-mod docutils literal">collections</code></a> module has some ABCs that can be used to test whether

a class or instance provides a particular interface, for example, is it

hashable or a mapping.

This module provides the following class:

class <code class="descclassname">abc.</code><code class="descname">ABCMeta</code><a class="headerlink" href="#abc.ABCMeta" title="Permalink to this definition">¶</a></dt>

<dd>Metaclass for defining Abstract Base Classes (ABCs).

Use this metaclass to create an ABC. An ABC can be subclassed directly, and

then acts as a mix-in class. You can also register unrelated concrete

100

classes (even built-in classes) and unrelated ABCs as “virtual subclasses” –

101

these and their descendants will be considered subclasses of the registering

102

ABC by the built-in <a class="reference internal" href="functions.html#issubclass" title="issubclass"><code class="xref py py-func docutils literal">issubclass()</code></a> function, but the registering ABC

103

won’t show up in their MRO (Method Resolution Order) nor will method

104

implementations defined by the registering ABC be callable (not even via

105

<a class="reference internal" href="functions.html#super" title="super"><code class="xref py py-func docutils literal">super()</code></a>). <a class="footnote-reference" href="#id2" id="id1">[1]</a>

106

Classes created with a metaclass of <a class="reference internal" href="#abc.ABCMeta" title="abc.ABCMeta"><code class="xref py py-class docutils literal">ABCMeta</code></a> have the following method:

107

108

109

<code class="descname">register</code>(subclass)<a class="headerlink" href="#abc.ABCMeta.register" title="Permalink to this definition">¶</a></dt>

110

<dd>Register subclass as a “virtual subclass” of this ABC. For

111

example:

112

<div class="highlight-python"><div class="highlight"><pre>from abc import ABCMeta

113

114

class MyABC:

115

__metaclass__ = ABCMeta

116

117

MyABC.register(tuple)

118

119

assert issubclass(tuple, MyABC)

120

assert isinstance((), MyABC)

121

</pre></div>

122

</div>

123

</dd></dl>

124

125

You can also override this method in an abstract base class:

126

127

128

<code class="descname">__subclasshook__</code>(subclass)<a class="headerlink" href="#abc.ABCMeta.__subclasshook__" title="Permalink to this definition">¶</a></dt>

129

<dd>(Must be defined as a class method.)

130

Check whether subclass is considered a subclass of this ABC. This means

131

that you can customize the behavior of <code class="docutils literal">issubclass</code> further without the

132

need to call <a class="reference internal" href="#abc.ABCMeta.register" title="abc.ABCMeta.register"><code class="xref py py-meth docutils literal">register()</code></a> on every class you want to consider a

133

subclass of the ABC. (This class method is called from the

134

<code class="xref py py-meth docutils literal">__subclasscheck__()</code> method of the ABC.)

135

This method should return <code class="docutils literal">True</code>, <code class="docutils literal">False</code> or <code class="docutils literal">NotImplemented</code>. If

136

it returns <code class="docutils literal">True</code>, the subclass is considered a subclass of this ABC.

137

If it returns <code class="docutils literal">False</code>, the subclass is not considered a subclass of

138

this ABC, even if it would normally be one. If it returns

139

<code class="docutils literal">NotImplemented</code>, the subclass check is continued with the usual

140

mechanism.

141

</dd></dl>

142

143

For a demonstration of these concepts, look at this example ABC definition:

144

<div class="highlight-python"><div class="highlight"><pre>class Foo(object):

145

def __getitem__(self, index):

146

...

147

def __len__(self):

148

...

149

def get_iterator(self):

150

return iter(self)

151

152

class MyIterable:

153

__metaclass__ = ABCMeta

154

155

@abstractmethod

156

def __iter__(self):

157

while False:

158

yield None

159

160

def get_iterator(self):

161

return self.__iter__()

162

163

@classmethod

164

def __subclasshook__(cls, C):

165

if cls is MyIterable:

166

if any("__iter__" in B.__dict__ for B in C.__mro__):

167

return True

168

return NotImplemented

169

170

MyIterable.register(Foo)

171

</pre></div>

172

</div>

173

The ABC <code class="docutils literal">MyIterable</code> defines the standard iterable method,

174

<a class="reference internal" href="stdtypes.html#iterator.__iter__" title="iterator.__iter__"><code class="xref py py-meth docutils literal">__iter__()</code></a>, as an abstract method. The implementation given

175

here can still be called from subclasses. The <code class="xref py py-meth docutils literal">get_iterator()</code> method

176

is also part of the <code class="docutils literal">MyIterable</code> abstract base class, but it does not have

177

to be overridden in non-abstract derived classes.

178

The <a class="reference internal" href="#abc.ABCMeta.__subclasshook__" title="abc.ABCMeta.__subclasshook__"><code class="xref py py-meth docutils literal">__subclasshook__()</code></a> class method defined here says that any class

179

that has an <a class="reference internal" href="stdtypes.html#iterator.__iter__" title="iterator.__iter__"><code class="xref py py-meth docutils literal">__iter__()</code></a> method in its

180

<a class="reference internal" href="stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal">__dict__</code></a> (or in that of one of its base classes, accessed

181

via the <a class="reference internal" href="stdtypes.html#class.__mro__" title="class.__mro__"><code class="xref py py-attr docutils literal">__mro__</code></a> list) is considered a <code class="docutils literal">MyIterable</code> too.

182

Finally, the last line makes <code class="docutils literal">Foo</code> a virtual subclass of <code class="docutils literal">MyIterable</code>,

183

even though it does not define an <a class="reference internal" href="stdtypes.html#iterator.__iter__" title="iterator.__iter__"><code class="xref py py-meth docutils literal">__iter__()</code></a> method (it uses

184

the old-style iterable protocol, defined in terms of <a class="reference internal" href="../reference/datamodel.html#object.__len__" title="object.__len__"><code class="xref py py-meth docutils literal">__len__()</code></a> and

185

<a class="reference internal" href="../reference/datamodel.html#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal">__getitem__()</code></a>). Note that this will not make <code class="docutils literal">get_iterator</code>

186

available as a method of <code class="docutils literal">Foo</code>, so it is provided separately.

187

</dd></dl>

188

189

It also provides the following decorators:

190

191

192

<code class="descclassname">abc.</code><code class="descname">abstractmethod</code>(function)<a class="headerlink" href="#abc.abstractmethod" title="Permalink to this definition">¶</a></dt>

193

<dd>A decorator indicating abstract methods.

194

Using this decorator requires that the class’s metaclass is <a class="reference internal" href="#abc.ABCMeta" title="abc.ABCMeta"><code class="xref py py-class docutils literal">ABCMeta</code></a> or

195

is derived from it.

196

A class that has a metaclass derived from <a class="reference internal" href="#abc.ABCMeta" title="abc.ABCMeta"><code class="xref py py-class docutils literal">ABCMeta</code></a>

197

cannot be instantiated unless all of its abstract methods and

198

properties are overridden.

199

The abstract methods can be called using any of the normal ‘super’ call

200

mechanisms.

201

Dynamically adding abstract methods to a class, or attempting to modify the

202

abstraction status of a method or class once it is created, are not

203

supported. The <a class="reference internal" href="#abc.abstractmethod" title="abc.abstractmethod"><code class="xref py py-func docutils literal">abstractmethod()</code></a> only affects subclasses derived using

204

regular inheritance; “virtual subclasses” registered with the ABC’s

205

<code class="xref py py-meth docutils literal">register()</code> method are not affected.

206

Usage:

207

<div class="highlight-python"><div class="highlight"><pre>class C:

208

__metaclass__ = ABCMeta

209

@abstractmethod

210

def my_abstract_method(self, ...):

211

...

212

</pre></div>

213

</div>

214

215

Note

216

Unlike Java abstract methods, these abstract

217

methods may have an implementation. This implementation can be

218

called via the <a class="reference internal" href="functions.html#super" title="super"><code class="xref py py-func docutils literal">super()</code></a> mechanism from the class that

219

overrides it. This could be useful as an end-point for a

220

super-call in a framework that uses cooperative

221

multiple-inheritance.

222

</div>

223

</dd></dl>

224

225

226

227

<code class="descclassname">abc.</code><code class="descname">abstractproperty</code>([fget[, fset[, fdel[, doc]]]])<a class="headerlink" href="#abc.abstractproperty" title="Permalink to this definition">¶</a></dt>

228

<dd>A subclass of the built-in <a class="reference internal" href="functions.html#property" title="property"><code class="xref py py-func docutils literal">property()</code></a>, indicating an abstract property.

229

Using this function requires that the class’s metaclass is <a class="reference internal" href="#abc.ABCMeta" title="abc.ABCMeta"><code class="xref py py-class docutils literal">ABCMeta</code></a> or

230

is derived from it.

231

232

instantiated unless all of its abstract methods and properties are overridden.

233

The abstract properties can be called using any of the normal

234

‘super’ call mechanisms.

235

Usage:

236

<div class="highlight-python"><div class="highlight"><pre>class C:

237

__metaclass__ = ABCMeta

238

@abstractproperty

239

def my_abstract_property(self):

240

...

241

</pre></div>

242

</div>

243

This defines a read-only property; you can also define a read-write abstract

244

property using the ‘long’ form of property declaration:

245

<div class="highlight-python"><div class="highlight"><pre>class C:

246

__metaclass__ = ABCMeta

247

def getx(self): ...

248

def setx(self, value): ...

249

x = abstractproperty(getx, setx)

250

</pre></div>

251

</div>

252

</dd></dl>

253

254

Footnotes

255

256

257

258

<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>C++ programmers should note that Python’s virtual base class

259

concept is not the same as C++’s.</td></tr>

260

</tbody>

261

</table>

262

</div>

263

264

265

</div>

266

</div>

267

</div>

268

269

270

<h4>Previous topic</h4>

271

<a href="contextlib.html"

272

title="previous chapter">28.7. <code class="docutils literal">contextlib</code> — Utilities for <code class="docutils literal">with</code>-statement contexts</a>

273

<h4>Next topic</h4>

274

<a href="atexit.html"

275

title="next chapter">28.9. <code class="docutils literal">atexit</code> — Exit handlers</a>

276

277

278

<li><a href="../bugs.html">Report a Bug</a></li>

279

<li><a href="../_sources/library/abc.txt"

280

rel="nofollow">Show Source</a></li>

281

</ul>

282

283

284

<h3>Quick search</h3>

285

286

287

288

289

290

</form>

291

292

Enter search terms or a module, class or function name.

293

294

</div>

295

296

</div>

297

</div>

298

299

</div>

300

301

<h3>Navigation</h3>

302

<ul>

303

304

<a href="../genindex.html" title="General Index"

305

>index</a></li>

306

307

<a href="../py-modindex.html" title="Python Module Index"

308

>modules</a> |</li>

309

310

<a href="atexit.html" title="28.9. atexit — Exit handlers"

311

>next</a> |</li>

312

313

<a href="contextlib.html" title="28.7. contextlib — Utilities for with-statement contexts"

314

>previous</a> |</li>

315

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

316

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

317

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

318

<li>

319

2.7.12

320

<a href="../index.html">Documentation</a> »

321

</li>

322

323

<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>

324

<li class="nav-item nav-item-2"><a href="python.html" >28. Python Runtime Services</a> »</li>

325

</ul>

326

</div>

327

328

329

330

The Python Software Foundation is a non-profit corporation.

331

<a href="https://www.python.org/psf/donations/">Please donate.</a>

332

333

Last updated on Sep 20, 2016.

334

<a href="../bugs.html">Found a bug</a>?

335

336

Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.3.3.

337

</div>

338

339

</body>

340

</html>

b'\\ No newline at end of file'

Older »