Adjust Inversion of Control definition

[seddonym]

Summary

Adjusts the IoC glossary definition as per our discussion offline.

IMO the existing definition isn't quite right, inversion of control is a broader concept not limited to relationships between I/O logic and business logic.

Pull Request Check List

• Typos aside (please, always submit typo fixes!), I understand that this pull request may be closed in case there was no previous discussion.
• Added tests for changed code.
  • The CI fails with less than 100% coverage.
• New APIs are added to our typing tests at https://github.com/hynek/svcs/blob/main/tests/typing/.
• Updated documentation for changed code.
  • New functions/classes have to be added to docs/core-concepts.md or one of the integration guides by hand.
  • Changed/added classes/methods/functions have appropriate versionadded, versionchanged, or deprecated directives.
    • The next version is the second number in the current release + 1. The first number represents the current year. So if the current version on PyPI is 23.1.0, the next version is gonna be 23.2.0. If the next version is the first in the new year, it'll be 24.1.0.
• Documentation in .rst and .md files is written using semantic newlines.
• Changes (and possible deprecations) are documented in the changelog.
• Consider granting push permissions to the PR branch, so maintainers can fix minor issues themselves without pestering you.

[hynek]

@bobthemighty? 😇

[bobthemighty]

@bobthemighty? 😇

Inversion of control means that your application doesn't invoke something at all. Instead your application is invoked by the other thing. Hence the Hollywood principle. You don't invoke the lower layers, they invoke you.

For a long time, if you wanted to build a web service, you needed to write code that would listen on a socket, parse an incoming message, then do something useful with that.

In other words, your code controlled the whole stack.

In modern frameworks, the control is inverted: you register a handler to a URL, and you get called when it's time to do some work. This is true of many kinds of framework. It's so ubiquitous that you probably don't think of there being any alternative.

I would gently repeat the advice to just not mention IOC at all. This definition is incorrect and you'll get snarky issues forevermore demanding that you reword things.

[seddonym]

What do you see as incorrect about it Bob? Everything you say is what I mean too.

Perhaps it's the use of the word 'program'. An application is running both custom and framework code, so one way of seeing it is that the framework bit of the application is calling the custom bit indirectly. But perhaps it's a confusing way of putting it.

Mentioning frameworks is just an example. The important thing IMO is the indirect invocation, IoC could happen within a framework just as much as between a framework and custom code.

My vote would be to keep trying for a definition. It's not a complicated idea, it's useful for people to understand, it's just that we don't have a precise common language to talk about it with, IMO.

[hynek]

Alright, I've meditated over this and I think I have a compromise that maybe everyone can live with by using a relevant example and adding a bunch of weasel words:

Inversion of Control (IoC) describes the concept of your code being invoked by someone else -- usually based on some kind of configuration.

That's why it's sometimes called the Hollywood Principle: "Don't call us, we'll call you."

From the perspective of the user, this usually means that third-party lower-level code (socket listeners, web frameworks, object observers) invokes your higher-level code (business logic).

A service locator like svcs is an example for IoC, because you tell it how to create services by defining a factory for a type and svcs will then invoke that factory when the user asks for a service of said type.

[seddonym]

From the perspective of the user, this usually means that third-party lower-level code (socket listeners, web frameworks, object observers) invokes your higher-level code (business logic).

Personally I would change 'higher-level code (business logic)' just to 'custom code'.

A service locator like svcs is an example for IoC

'for' -> 'is'?

Otherwise, I like it!